feat(windows): native Windows kernel runtime — Contract/Ports/Adapters across the reviewed capability DAG

[huangzesen]

feat(windows): native Windows kernel runtime — Contract/Ports/Adapters across the reviewed capability DAG

Summary

Implements the reviewed Windows kernel blocker/parallelism DAG as one integrated change-set: every suitable Windows capability lands behind its owning Contract with a platform-neutral Core Port, a native Windows adapter, the preserved POSIX adapter, and shared contract tests. The construction frontier (C0+L1+W1 → K0) and CLI lifecycle host (R1) are complete; the refresh (W2/R2), daemon (D1–D3), avatar (A1), shell residuals (S1/S2), and portable-transport certification (P1–P7) lanes land as independent capability rows. Support is published only as a per-capability matrix (docs/references/windows-support.md) — never one boolean claim.

• WorkdirLease (L1): WindowsWorkdirLeaseAdapter — msvcrt byte 0/length 1 on .agent.lock, the frozen TUI-probe interop range (TUI PR docs(email): remove stale schedule API manual content #687: conflict→Block, missing→Allow, error→Unknown). Exact-argument pin runs on every platform; native contention/crash-release/probe tests run on Windows CI.
• Refresh watcher (W1/W2): Windows outer adapter + entrypoint + process mechanism (CIM command-line observation, OpenProcess liveness — never os.kill, which terminates on Windows; .suspend cooperative graceful stop; exact-PID forced stop). Core policy/renderer unchanged and platform-neutral.
• CLI lifecycle host (R1/C0): new capability-local AgentProcessScanPort (POSIX ps / Windows CIM) behind the duplicate-launch guard; platform-honest stop signals (SIGTERM/SIGINT vs SIGINT/SIGBREAK → .suspend); CPR relaunch via shared detached creation flags; canonical matcher accepts both path separators (doctor copy kept in parity).
• Daemon (D1–D3): the .daemon-state.lock transaction lock gains a capability-local msvcrt byte-range seam (POSIX flock byte-for-byte unchanged); WindowsDaemonProcessPort maps PRIVATE_PROCESS_GROUP to per-spawn Job Objects (suspended spawn → assign → NtResumeProcess, no kill-on-close, mirroring POSIX survival semantics) and INHERITED_SUPERVISOR_GROUP to exact-child-only termination; WindowsDaemonSupervisorAdapter carries the one-shot secret capsule as an inherited pipe HANDLE via STARTUPINFO.lpAttributeList["handle_list"] (env holds only the handle number — bytes never touch disk/argv/env), with three Windows entrypoint mirrors that adopt the handle onto the shared fd wire and reuse the POSIX read/dispatch logic verbatim; Windows process-incarnation identity (windows:<creation_filetime>) keeps every ownership-guarded signal path fail-closed; interactive Claude stays fail-loud unsupported on Windows.
• Avatar (A1): WindowsAvatarLauncherAdapter with the documented honest terminate mapping — on Windows terminate and force_terminate are both forceful TerminateProcess; no fake graceful tier.
• Shell (S1/S2): nested-sandbox containment fixed to os.sep (was hardcoded /, rejecting every legitimate nested working_dir on Windows); msvcrt state-lock byte range now exact-argument-pinned.
• Portable transports (P1–P7): presence/journal/notification/mail/migration/git certified portable; two real encoding defects fixed (mail.py, git_cli.py writes lacked encoding="utf-8"); certification runs on the new Windows CI lane.
• agent-runtime contract: new src/lingtai/kernel/base_agent/CONTRACT.md (lingtai.kernel.agent-runtime.v1, 8 clauses) composing the capability contracts; cross-repo clauses explicitly proposed, nothing marked mutually accepted unilaterally.

Architecture / Contracts

Every Windows implementation follows Contract + Ports & Adapters: Core never branches on platform; selectors fail loudly for genuinely unsupported platforms; no catch-all Platform/ProcessSupervisor object exists. Capability-local locks stay separate (.agent.lock lease ≠ shell .state.lock ≠ daemon .daemon-state.lock). New/updated Contracts: workdir_lease, refresh_watcher, base_agent (new), tools/avatar, tools/bash, tools/daemon, kernel/daemon_supervisor. ConPTY/interactive terminal remains unsupported (fail-loud) by design; the WeChat poller lock likewise.

Capability matrix

See docs/references/windows-support.md — per-capability rows with owning contract, state (supported / implemented, native-CI-gated / unsupported (fail-loud)), mechanism, and evidence. The Windows CI lane (.github/workflows/kernel-windows-pr.yml, windows-latest/py3.12) executes the platform-marked tiers natively on this PR.

Validation

All runs on a fresh py3.12 venv in an isolated worktree at base 5f3c1733 (origin/main; unmoved at push time).

• Baseline receipt (untouched tree): python -m pytest tests/ -q → 1 failed, 5787 passed, 9 skipped — the one failure is tests/test_skills.py::test_skills_setup_hard_copies_standalone_intrinsic_skills (pre-existing content assertion on main, unrelated to this PR).
• Candidate receipt (this change-set): python -m pytest tests/ -q → 1 failed, 5857 passed, 28 skipped in 223s — the same single pre-existing failure only. Net +70 passing tests; the additional skips are the new windows_mechanism native tiers, inert on POSIX.
• Focused validators green: tests/test_architecture_documents.py, tests/test_docs_governance.py, tests/test_anatomy_drift_checker.py, tests/test_environment_variable_catalogue.py; git diff --check clean.
• Cross-platform Windows pins run on POSIX too: exact msvcrt byte ranges (lease, shell state lock, daemon ledger lock), exact detached-spawn shapes (refresh, avatar, supervisor capsule handle_list wire), selector routing, and the boot-path import graph with fcntl/termios/pty/grp blocked.
• Native Windows receipts (green at head dafe64b2): Kernel Windows PR contract run 29679309133 — contract tiers 237 passed, 15 skipped, lifecycle smoke 56 passed (test_agent.py + test_lifecycle_daemon_shutdown.py entirely green on windows-latest, i.e. the real construct→start→presence→stop path natively). Shell PowerShell PR contract run 29679309116 — pass. Two earlier red rounds were test-side platform couplings (fixed in the two follow-up commits, production code untouched) plus one pre-existing flaky native shell test (test_native_job_object_cancel_after_root_exit_terminates_descendant_tree: pass → fail on an unrelated-tests-only commit → pass on rerun; the Job-Object mechanism was identical throughout).

Residuals

• Pre-existing on main, untouched: test_skills.py::test_skills_setup_hard_copies_standalone_intrinsic_skills content assertion (baseline failure); Windows durable-state fsync boundary is file-level by design; mail claim-protocol directory-replace edge under adversarial concurrency (guarded, observed under native CI).
• Introduced, documented normatively: Windows supervisor exact-run reclaim is narrower than POSIX killpg (identity-guarded exact PIDs only; grandchildren outside the execution Port's Job are not swept — see tools/daemon/CONTRACT.md §Windows invariants).
• Environmental: detached children inherit a host's kill-on-close Job Object if the parent runs inside one (no CREATE_BREAKAWAY_FROM_JOB attempt; breakaway permission cannot be assumed).
• Pinned deliberately: the lingtai-agent.exe console form is not matched by the duplicate-launch scan (runtime relaunches always use the module form; the workdir lease remains the exclusion authority).
• Cross-repo: the kernel-side half of the TUI byte-0 interop is tested natively here; the two-repository one-host native run remains the outstanding receipt before any mutual minimal-lifecycle claim.

Non-goals

• No ConPTY/interactive terminal adapter (deferred by design; fail-loud).
• No WeChat poller Windows lock (fail-loud UnsupportedPlatformError preserved).
• No renaming of portable Posix* adapters (historical names; portable transports certified as-is).
• No cross-repo mutual-acceptance claim: agent-runtime.compat.v1 stays proposed until both repos' contract revisions cross-reference; the two-repo one-host native interop run is an explicitly recorded outstanding receipt.
• Not merged by this workflow: review happens on the PR.

🤖 Generated with Claude Code