Skip to content

feat(ops): expose structured personal Server lifecycle operations #2116

Closed

Description

@knqiufan

Goal

Expose reliable, noninteractive personal Server configuration/service operations to Desktop through an independent Installer/Ops boundary. Preserve the existing single current-user service semantics while supporting Windows and macOS first.

Parent: #2114. Release: #2099. Linux adapters are optional follow-on work under #2110 / #2111.

PR breakdown

  • PR 11-A — Structured independent lifecycle operations. Provide versioned requests/results, stable errors, preflight/apply/status/recovery and fixed install/register/start/stop/restart/remove operations. Reuse or extract current configuration validation, registration ownership, locking, launcher and explicit-stop semantics. Define supported login-start choices per platform and safe handling of damaged environments.
  • PR 11-B — Constrained Desktop native bridge. Integrate reviewed operations and typed results with native validation, deadlines, bounded output, safe cancellation and operation-status lookup. The renderer never supplies arbitrary shell commands, executable paths, service names or unrestricted configuration writes.

Dependencies and coordination

Acceptance criteria

  • Operations have explicit inputs, machine-readable success/partial-failure/uncertain results and recovery actions, with no hidden terminal prompt. Structured output and authorization to mutate remain separate controls.
  • Installer/Ops is callable when the Server is stopped. Missing/damaged managed Python does not prevent independent inspection and supported stop/removal/repair of owned registrations.
  • Current-user Task Scheduler on Windows and LaunchAgent on macOS share the established ownership/state contract. No root/SYSTEM service or Desktop-owned Server supervisor is introduced.
  • CLI and Desktop do not create competing registrations, bypass each other's locks, or silently adopt unknown live listeners/foreign services.
  • Preserve distinct support, registration, definition, manager ownership, manager state, liveness/readiness and recovery facts. A nonzero result may still carry valid unhealthy state.
  • Explicit stop suppresses unintended automatic restart. Supported login-start settings are truthfully represented; close Desktop, stop Server and remove registration are different operations.
  • Configuration validation/apply preserves protected environment identity and existing choices. Secrets use protected input/references, never command arguments, renderer storage, logs or progress records.
  • An approved setup/start action may include a disclosed readiness probe; passive observation and ordinary Memory requests do not silently probe configured models/dependencies.
  • Cancellation stops waiting only at documented boundaries; uncertain mutation outcomes are inspected through durable status before retry. Forced termination has recoverable state.
  • Native lifecycle, identity, stale/foreign registration, port-conflict, repeat-call, explicit-stop and damaged-environment scenarios pass on Windows/macOS, with installed acceptance linked from their platform issues.

Non-goals

A generic shell/process/filesystem bridge, remote Server management, a second service state model, arbitrary database migration, automatic Agent setup, or mandatory Linux implementation.

Metadata

Metadata

Assignees

Labels

desktopDesktop application, native platform integration, and packaging

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions