Support opt-in session restarts through [wdl] session_policy

[cnluzhang]

Summary

• Adds [wdl] session_policy (preserve default, restart opt-in) to the Wrangler config. The CLI parses the private table, strips it from the temporary bundle config, and sends sessionPolicy on the deploy manifest.
• Verifies control applied it: a deploy response that does not echo the policy leaves the version unpromoted, and a promote response that does not confirm it fails the deploy — an older control plane cannot leave a restart worker running as preserve unnoticed.
• The policy inherits into [env.<name>] like workers_dev; an env-level [wdl] replaces the top-level table whole.
• asRecord now rejects a TOML datetime as a table, so a bare date can no longer silently stand in for [wdl], [triggers], [durable_objects], or an env table.
• Docs: the deploy chapter owns the policy, the Durable Objects chapter owns facet/alarm behavior, English and Chinese in step.

Validation

• npm run lint / typecheck / format:check
• npm test — 539 pass; nine mutations of the new contracts verified to fail the suite
• Live integration (npm run test:integration:live) against the released wdl.20260804.2 images — 20 pass
• Manual end-to-end on that stack: a pure-WebSocket worker with no Durable Object bindings deploys with session_policy = "restart", promotion closes the live socket with 1012 service restart, and a fresh session reaches the new version

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-in deploy-time session restart policy to the WDL CLI/Wrangler config pipeline, ensuring the CLI both sends the policy to control and verifies control actually applied it so older control planes can’t silently run “preserve” when “restart” was requested.

Changes:

• Introduces [wdl] session_policy parsing (preserve default, restart opt-in), strips [wdl] from the temporary Wrangler bundle config, and sends sessionPolicy on the deploy manifest only when set to restart.
• Hardens config/table validation by making asRecord reject TOML datetimes (Date instances), preventing bare dates from being mistaken for tables.
• Extends deploy/promotion validation: fails early if deploy response doesn’t echo restart, and fails if promote response doesn’t confirm restart plus a positive restartSequence; updates docs/tests accordingly.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/unit/helpers.js	Adds a shared deployPromoteFetch helper to reduce repeated controlFetch stubs in deploy tests.
tests/unit/cli-output.test.js	Adds coverage for formatDiagnosticValue formatting/escaping (NaN/Infinity/Date/control bytes).
tests/unit/cli-deploy.test.js	Adds unit coverage for session policy parsing, inheritance, wire behavior, and control-plane acknowledgement enforcement; refactors fetch mocking to use the new helper.
templates/AGENTS.md	Documents session policy behavior for generated/agent-facing project guidance.
README.md	Updates wording around the hosted offering (“hosted preview”) and clarifies expectations.
README-zh.md	Mirrors README hosted-preview wording in Chinese.
lib/wrangler/utils.js	Updates asRecord to reject Date values so TOML datetimes aren’t treated as empty tables.
lib/wrangler/config.js	Adds parseSessionPolicy, strips [wdl] from bundle config (including envs), and rejects hoisted session_policy outside [wdl].
lib/wrangler-pack.js	Wires session policy parsing into manifest construction; only sends sessionPolicy when restart.
lib/output.js	Enhances diagnostic formatting for NaN/Infinity and TOML datetime (Date) values while preserving terminal escaping.
GUIDE.md	Documents [wdl] session_policy in the compatibility table and deploy/DO guidance, plus troubleshooting entries.
GUIDE-zh.md	Chinese counterpart updates to keep docs aligned with GUIDE.md.
docs/secrets.md	Notes that worker-level secret promotions also restart sessions when session_policy = "restart".
docs/secrets-zh.md	Chinese counterpart of the secrets doc update.
docs/README.md	Adds a docs index entry pointing session policy readers to deploy docs.
docs/README-zh.md	Chinese counterpart of the docs index entry.
docs/env-overrides.md	Clarifies [wdl] is inheritable into envs (like workers_dev).
docs/env-overrides-zh.md	Chinese counterpart of env override inheritance clarification.
docs/durable-objects.md	Adds a detailed “Session policy and facets” section explaining restart semantics.
docs/durable-objects-zh.md	Chinese counterpart of the DO session policy section.
docs/deploy.md	Adds a dedicated session policy section and adds related common-error entries.
docs/deploy-zh.md	Chinese counterpart of the deploy session policy documentation.
commands/deploy.js	Enforces deploy/promotion acknowledgement for restart policy (and refactors manifest inspection via asRecord).
CHANGELOG.md	Adds an Unreleased entry documenting the new opt-in session restart capability.
.claude/skills/wdl-deploy/SKILL.md	Updates the deploy guidance distillation to include session policy behavior and doc pointers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (1)

package.json:53

• Using a caret range in package.json overrides means published installs (which don’t use the repo lockfile) may pull a newer undici minor/patch than the one you validated here. Since this override is presumably an audit/compatibility pin, consider pinning to the exact version that package-lock.json resolves to for reproducibility.

  "overrides": {
    "undici": "^7.29.0"
  },

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (1)

lib/output.js:65

• formatDiagnosticValue can still throw because JSON.stringify throws on values like BigInt and circular structures. This contradicts the comment that diagnostics must never throw, and can turn a user-facing validation error into an unexpected crash when formatting an invalid config value.

    const stamp = Number.isNaN(value.getTime()) ? "invalid" : value.toISOString();
    return escapeTerminalText(`datetime ${stamp}`);
  }
  return escapeTerminalText(JSON.stringify(value));
}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a855abe45

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".