Tracking Issue: local Server availability and service installation

[knqiufan]

Status

RFC #1299 has been accepted and merged. This issue now tracks implementation of the accepted design. The merged RFC is the source of truth for the public contract, responsibility boundaries, security rules, and platform qualification requirements.

Implementation may be delivered through independently reviewed pull requests. A platform must continue to report unsupported until its adapter ships and passes the required base and native lifecycle tests on a matching runner.

Problem

powercontext server run is intentionally a foreground process. Agent integrations depend on a reachable Server and fail open when it is unavailable, so closing the terminal or restarting a personal machine can leave recall and capture unavailable during later agent sessions.

PowerContext needs a clear boundary among:

• host-visible Server-unavailability diagnostics in agent integrations;
• correlated installed-environment diagnostics in powercontext doctor;
• opt-in native per-user service installation for personal use through a distribution/service-install layer;
• container or administrator-managed services for managed deployments.

The Server role continues to own foreground process construction and powercontext server run. Integrations remain fail-open and do not install, start, or supervise the Server. Native service adapters belong to the distribution/service-install layer rather than src/powercontext/server.

Accepted design

• RFC: docs(rfc): define local Server service-installation boundaries #1299

• RFC state: accepted and merged

• Personal lifecycle commands:

  powercontext service install
  powercontext service uninstall
  powercontext service status
  

• The commands manage one opt-in service for the current operating-system user. There are no named profiles or privileged/system-wide installation modes.

• The intended endpoint comes from local ServerSettings and must use a loopback bind. Client or integration server_url values do not select the local service registration.

• service install performs endpoint preflight, installs or reconciles a verified PowerContext-owned native artifact, enables it for future logins, and starts it immediately unless a valid PowerContext Server is already live.

• service uninstall stops a manager-owned process before removing the verified registration. It never kills a process only because it occupies the intended port.

• service status reports independent support, registration, definition, manager, liveness, and log-location facts in human-readable and JSON forms.

• Service artifacts contain no complete environment, API keys, bearer tokens, or provider credentials. File-backed settings and secrets remain a separate concern under the existing pydantic-settings direction and are not a general-availability condition for this work.

Tracking checklist

Design

• Accept RFC docs(rfc): define local Server service-installation boundaries #1299
• Fix the public lifecycle interface at powercontext service install|uninstall|status
• Keep configuration and credential handoff separate from the service lifecycle contract
• Define responsibility boundaries for the Server role, integrations, diagnostics, service-install layer, and managed deployments

Host-visible availability diagnostics

• Surface a content-free server_unavailable outcome through each integration's host-appropriate visible channel while preserving fail-open behavior
• Bound or deduplicate repeated Server-unavailable warnings
• Keep authentication failure, version mismatch, invalid response, empty success, and Server unavailability distinct
• Add per-host acceptance evidence for warning visibility and bounded repetition

Shared service state and doctor diagnostics

• Implement the shared state model for support, registration, definition, manager, liveness, and log location
• Extend powercontext doctor to correlate registration, native manager state, Server liveness, and Server readiness for the registered local endpoint
• Keep unsupported and not_installed advisory when the optional service is not registered
• Keep remote targets and nonmatching loopback targets independent of local service registration and manager state
• Preserve equivalent human-readable and JSON diagnostic facts and safe recovery actions

Distribution/service-install layer

• Add the top-level powercontext service command group only when the CLI and ready-to-run Server role are installed together
• Implement the adapter protocol and distribution-owned internal launcher outside the Server role
• Implement loopback and endpoint preflight, including valid PowerContext Server, address conflict, and unreachable outcomes
• Implement idempotent install, atomic reconciliation, post-commit start-failure reporting, and executable-drift detection
• Implement stop-before-remove uninstall and verified-ownership cleanup
• Prevent privilege elevation, foreign-artifact overwrite, credential disclosure, and duplicate Server startup

Native per-user adapters

• Linux: systemd --user, without /etc writes or enabling linger
• macOS: current-user LaunchAgent with explicit per-user stdout and stderr paths
• Windows: current-user Task Scheduler logon task with explicit per-user Server logs
• Fix and test project-owned native identifiers, ownership markers, definition versions, and bounded restart policies

Documentation and validation

• Document interactive personal, persistent personal, and managed deployment profiles
• Document install, status, uninstall, reconciliation after upgrades, recovery actions, and log locations
• Add focused tests for rendering, ownership, loopback validation, reconciliation, rollback, launcher preflight, status semantics, and redaction
• Add native register, query, start, stop, and remove tests on matching operating-system runners
• Keep release documentation and service status honest about actual platform availability
• Require the base install and Server smoke tests before advertising Windows adapter support

Delivery

Implementation may be split into separate pull requests for:

1. host-visible integration diagnostics;
2. correlated doctor diagnostics and the shared service state model;
3. the distribution-owned CLI, internal launcher, and adapter protocol;
4. Linux, macOS, and Windows adapters;
5. documentation and platform integration tests.

Link accepted implementation pull requests to this issue and update the checklist as they land. Each pull request should preserve the accepted RFC contract and include the tests and documentation needed for the behavior it advertises.

Out of scope

• Starting or installing the Server from an agent hook
• Enabling persistent service installation during setup
• Installing a machine-wide, root, SYSTEM, or administrator service
• Public binding, remote multi-user service profiles, or managed-deployment automation
• A PowerContext-specific supervisor
• A portable secret store or environment snapshot

[PsiACE]

@knqiufan Thanks for the proposal. I think autostart belongs in a distribution/service-install layer rather than the Server CLI. First, plugins should surface Server unavailability, with doctor providing a clear diagnostic. Personal installs can use native user services through the distribution layer, while managed deployments should use containers or administrator-managed system services. Let’s scope the issue around this boundary before implementation.

[PsiACE]

This is a good fit for an RFC so we can discuss and agree on the design. Once accepted, a tracking issue can track progress and split the implementation.

[knqiufan]

@PsiACE Thanks for clarifying the boundary and process. That makes sense. I will open a docs-only RFC to discuss and agree on the responsibility split among plugin-visible Server availability, doctor diagnostics, the distribution/service-install layer for personal installs, and container or administrator-managed services for managed deployments before any implementation. I will link the RFC PR here once it is open.

[knqiufan]

RFC opened for design discussion: #1299. I have updated this issue to track RFC acceptance and the subsequent diagnostic, distribution/service-install, and native-adapter work. Implementation remains blocked until the RFC is accepted.

[knqiufan]

@PsiACE RFC #1299 has now been accepted and merged. I updated this tracking issue to reflect the accepted command contract, responsibility boundaries, delivery split, platform qualification, and validation requirements.

I would like to continue with the implementation. To keep review and rollback bounded, I propose the following sequence:

1. Add the shared service state model, the distribution-owned powercontext service CLI and adapter protocol, and the internal launcher preflight.
2. Add correlated powercontext doctor diagnostics after the current stacked CLI work in feat(cli): add setup select for explicit multi-host plugin install #1311 and feat(cli): add doctor integrations for first-class host status #1314 land, so the service checks build on the settled doctor surface.
3. Deliver the native adapters as independently reviewed changes: Linux systemd --user, macOS LaunchAgent, and Windows Task Scheduler. Each platform will remain unsupported until its native lifecycle tests and required base smoke tests pass on a matching runner.
4. Add host-visible, content-free, bounded server_unavailable diagnostics for each supported integration while preserving fail-open behavior and distinct failure outcomes.
5. Include the documentation and platform acceptance evidence with the implementation slice that advertises each behavior.

Could you please confirm whether this split and order match the intended project priority? If this plan looks good, I can proceed with the feature according to it.