selftune service installs and controls the same SelfTune CLI binary under the
native user-level OS supervisor. The desktop app and CLI do not maintain
separate background executables.
Usage
On Linux, installation may enable systemd user lingering so SelfTune can start
at boot without an interactive login. This is best-effort because some systems
require additional authorization.
Installation is idempotent. Packaged desktop releases copy their signed,
manifest-verified runtime to a versioned stable application-support path before
registering it; direct CLI installs register the current CLI executable. The
definition records the version, state directory, dashboard assets, and port.
Local bearer credentials remain outside launchd, systemd, and Task Scheduler
definitions. An explicit install first authenticates to and stops the runtime
using the same state directory, then transfers the singleton to the service.
Runtime ownership and supervision are separate. A foreground CLI daemon is
CLI-owned without an OS supervisor, while a persistent service can be owned by
the CLI or desktop installer. The desktop preserves and attaches to registered
services with an equal, newer, or unknown version; it only replaces a service
that has an older valid SelfTune version. A directly started CLI daemon is not
terminated when the desktop app quits. A desktop child orphaned by an app crash
is authenticated and stopped before a later desktop instance replaces it.
That cleanup is bound to the original PID and runtime instance ID, so a delayed
desktop shutdown or Windows task cleanup cannot terminate a successor CLI
daemon. Service start and repair succeed only when the authenticated manifest
identifies a healthy OS-supervised runtime.
Options
--boot applies only to Windows and requires elevation. Linux boot persistence
uses user lingering rather than this flag; other default services start when
the user signs in. --owner is an advanced integration option; ordinary CLI
usage defaults to cli, and the desktop supplies desktop automatically.
Packaged integrations can also provide --executable, --resource-dir, and
--service-version. Older desktop builds that send --version remain compatible.
Diagnose and repair
selftune service install.
On Windows, service doctor inspects the fixed current-user mutation-lock scope
without creating service state. It reports fenced, ready_to_fence,
legacy_active_or_unverifiable, legacy_stale_repairable,
changed_during_inspection, or invalid_blocking_file. Only
legacy_stale_repairable can be changed by service repair-lock.
The maintenance commands accept only --json. They do not accept a state
directory, path, PID, candidate token, or force flag. Repair retains the proven
candidate in memory, acquires the per-user SQLite owner, reproves the complete
legacy file generation, and atomically replaces it with the permanent fence.
Never delete the lock file manually.
Rotate local authentication
selftune service uninstall to remove only the supervisor definition. Use
selftune uninstall for a complete teardown, including the Sync & Backup
credential and local state. Stopping or uninstalling the service preserves an
independently started CLI daemon.
On Linux, uninstall preserves user lingering because it is a user-global
setting that may keep other user services running. Only run
loginctl disable-linger "$USER" after considering those other services.
On Windows, stop, restart, reinstall, and uninstall also inspect the exact
loopback listener left after Task Scheduler ends. A surviving child receives an
instance-bound authenticated shutdown request only after fresh health checks
match its PID, runtime instance, owner, supervision mode, absolute executable
identity, port, and state directory. Final verification only scans the port, so
it cannot stop a successor. SelfTune fails closed on an ambiguous or foreign
listener, and uninstall retains the task and launcher artifacts until the old
runtime and port are proven clean.
Task registration and running state come from structured Task Scheduler
inventory and stable numeric result codes rather than localized system text.
SelfTune also resolves scheduler, listener-inspection, and hidden-launcher tools
to validated absolute executables under System32.
All Windows service mutations contend on one per-user SQLite ownership lock,
including commands that target different --config-dir values. The lock is held
by the live database connection and released by the operating system if its
process crashes or is forcibly terminated; there is no stale PID file to remove.
Legacy pre-SQLite releases are fenced out at their old lock path. A stale lock
from one of those releases is the only case handled by service repair-lock.
Receipt and legacy cleanup artifacts are moved to a generation-bound quarantine
name before deletion. SelfTune verifies the bytes after the move, restores a
mismatch without overwriting a replacement, and resumes a matching quarantine
after a crash. Cleanup authority remains durable until the task, listener,
artifacts, and journal or receipt have all converged.