Skip to content

Make Windows Runner lifecycle and deployment first-class #97

Description

@yyjeqhc

Context

#88 detached Job dogfood exposed a separate Windows operations problem: even with structured execution, Job observation, Computer Use, and detached execution, replacing or deploying the Windows Runner still depends on host-specific launcher behavior and out-of-band recovery steps.

This is post-0.3.8 follow-up work, not a blocker for v0.3.8. Detached execution from #88 already removes the most important self-maintenance failure mode by allowing owned work to survive a Runner process restart.

Dogfood evidence

On MSI, the production Runner was originally launched as:

Task Scheduler restrictive Job
  -> PowerShell supervisor
    -> webcodex-runner

That topology prevented the #88 detached supervisor from using CREATE_BREAKAWAY_FROM_JOB safely. Final #88 dogfood required a host-level launcher topology that kept the interactive user/session but placed the main Runner under a breakaway-capable process lineage:

Scheduled Task supervisor
  -> Win32_Process.Create
    -> cmd.exe
      -> webcodex-runner

The same work also exposed a lifecycle identification problem: a replacement wrapper that identified the main Runner only by executable path could mistake a surviving internal detached supervisor (webcodex-runner.exe --webcodex-internal-*) for the main Runner and therefore fail to start a replacement.

These are deployment/lifecycle concerns, not detached-execution ownership defects.

Direction

Add a narrow, first-class Windows Runner lifecycle/deployment substrate for a single local Runner installation.

It should make the supported topology and replacement contract explicit rather than relying on machine-private wrapper conventions.

At minimum, define and support:

  • an interactive-user/session-compatible launcher topology suitable for Computer Use;
  • a main Runner process that is not trapped in a non-breakaway outer Job when detached execution is enabled;
  • exact main-Runner identification that excludes internal detached supervisor/watchdog modes;
  • PID + process creation/start identity fencing before replacement effects;
  • bounded replacement and readiness observation using the exact new agent_instance_id and build/source identity;
  • rollback when a replacement cannot become Ready;
  • preservation of existing private ManagedChild / Job Object ownership semantics;
  • bounded diagnostics that distinguish launcher failure, stale Runner identity, and replacement registration failure.

Non-goals

Do not turn this into:

WMI or another bootstrap mechanism may be appropriate for the Windows installation topology, but it should remain part of the explicit Runner lifecycle/deployment boundary rather than an implicit fallback in ordinary tools.

Acceptance criteria

  • A documented/supported Windows launcher topology preserves the interactive desktop requirements needed by Computer Use and supports Add detached Job ownership handoff for Runner-restart survival #88 detached supervisor breakaway semantics.
  • Main Runner discovery cannot confuse --webcodex-internal-* processes with the primary Runner.
  • An operator can replace the exact current Runner with PID/start-identity fencing and without manually orchestrating multiple shell/WMI steps.
  • Replacement waits for and verifies a fresh agent_instance_id, expected build commit, and clean source identity.
  • Failed replacement has a bounded rollback path.
  • Existing detached Jobs survive a normal Runner replacement without special per-job handling.
  • Ordinary ManagedChild Job Object semantics remain unchanged.
  • MSI production dogfood covers successful replacement and one bounded failure/rollback case.

Scheduling

Target this after v0.3.8. Do not expand the v0.3.8 release scope for this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions