software-defence-factory 0.3.5 → 0.4.1

package/README.md

@@ -19,10 +19,12 @@ Choose the part you need:
 
 | Outcome | Command / guide |
 | --- | --- |
+| Set up an operator, worker and application | [Setup plan and acceptance checklist](docs/setup.md) |
 | Use the method with your existing agent | `software-defence-factory kit --output ./factory-kit` — exports a new staging directory |
 | Try the runtime without inference | `software-defence-factory demo` — Docker required; synthetic sample only |
 | Connect an existing repository | [Runtime quickstart](docs/quickstart.md) |
 | Understand installation and updates | [npm and npx](docs/npm.md) |
+| Restore a dashboard after boot or reconnect remotely | [Services and SSH tunnels](docs/services.md) |
 | Review the evidence and limits | [Qualification](docs/proof.md) |
 
 The runtime supplies policy and six focused skills to its isolated jobs. `init` configures a private installation; it does not modify the application or start work. Model access and the application's real check command must be configured before using it for delivery.
@@ -68,6 +70,7 @@ npm run check
 ```
 
 CI builds the dashboard and checks Node 22/24. A version increase merged to `main` is published to npm through the configured release workflow. Installed CLIs can update on invocation when all installations are stopped. See [release and update behavior](docs/npm.md).
+Managed Linux services can also opt into daily updates that reserve idle controllers, preserve stopped projects and restore the prior release if startup fails. See [service operation](docs/services.md).
 
 This is a test release. Synthetic qualification demonstrates control flow and isolation, not model quality, application correctness or production readiness. Follow [AGENTS.md](AGENTS.md) for contributions and [SECURITY.md](SECURITY.md) for the trust boundaries.
 

package/bin/software-defence-factory.mjs

@@ -8,6 +8,7 @@ import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, a
 import { admitIncident } from '../factory/incident.mjs';
 import { DEFAULT_DEMO_STATE } from '../factory/paths.mjs';
 import { bootstrap, registerInstallation, VERSION } from '../factory/updates.mjs';
+import { hasService, manageService, serviceDefinition, withServiceOperation, isManagedLaunch } from '../factory/services.mjs';
 
 try {
   const handled = await bootstrap(process.argv.slice(2));
@@ -94,7 +95,8 @@ async function stop() {
     const {pid}=json(lock);
     if(alive(pid)) {
       const identity=run('ps',['-p',String(pid),'-o','command=']);
-      if(!identity.includes(join(ROOT,'factory/supervisor.mjs'))||!identity.includes(state))throw new Error('PID identity changed; refusing to signal an unrelated process');
+      const controllerProcess=identity.includes(join(ROOT,'factory/supervisor.mjs'))||identity.includes(join(ROOT,'bin/software-defence-factory.mjs')+' serve');
+      if(!controllerProcess||!identity.includes(state))throw new Error('PID identity changed; refusing to signal an unrelated process');
       process.kill(pid,'SIGTERM');
       for(let i=0;i<40&&existsSync(lock);i++)await sleep(250);
       if(existsSync(lock))throw new Error('Stop unconfirmed; inspect supervisor and do not start replacement workers');
@@ -134,18 +136,27 @@ async function jobAction(action) {
 
 try {
   if(command==='init') { if(!flags.repo)throw new Error('init requires --repo /path/to/existing/git/repo');init(flags.repo,flags.agent,flags.check,flags.port); }
-  else if(command==='install')await install();
-  else if(command==='up')await up();
-  else if(command==='stop')await stop();
+  else if(command==='install')await withServiceOperation('install',install);
+  else if(command==='up') { if(hasService(state))await manageService('controller','start',state);else await withServiceOperation('up',up); }
+  else if(command==='stop') { if(hasService(state))await manageService('controller','stop',state);else await withServiceOperation('stop',stop); }
   else if(command==='serve') {
+    const managed=isManagedLaunch(state);
+    if(hasService(state)&&!managed)throw new Error('This installation is managed; use service start instead of foreground serve');
+    const launch=async()=>{
     if(process.getuid()===0)throw new Error('Use a dedicated unprivileged operator account');
     const lock=join(state,'supervisor.json');if(existsSync(lock)){if(alive(json(lock).pid))throw new Error('Supervisor already running');rmSync(lock);}
-    registerInstallation(state);await portFree(configAt(state).port);await stream(process.execPath,[join(ROOT,'factory/supervisor.mjs'),state]);
+    if(!existsSync(join(state,'engine.json')))throw new Error('Run install first');
+    run('docker',['image','inspect',configAt(state).image]);
+    registerInstallation(state);await portFree(configAt(state).port);
+    const { supervise } = await import('../factory/supervisor.mjs');await supervise(state);
+    };
+    if(managed)await launch();else await withServiceOperation('serve',launch);
   }
   else if(command==='service') {
-    configAt(state);const q=s=>JSON.stringify(s.replaceAll('%','%%'));
-    console.log(`[Unit]\nDescription=Software & Defence Factory\nAfter=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${q(ROOT)}\nExecStart=${q(process.execPath)} ${q(join(ROOT,'bin/software-defence-factory.mjs'))} serve --state ${q(state)}\nRestart=on-failure\nRestartSec=10\nTimeoutStopSec=30\nKillMode=control-group\nUMask=0077\n\n[Install]\nWantedBy=default.target`);
+    if(!positional.length || positional[0]==='print')console.log(serviceDefinition(state));
+    else await manageService('controller',positional[0],state,flags);
   }
+  else if(command==='tunnel')await manageService('tunnel',positional[0],state,flags);
   else if(command==='status') { const snapshot=await api(state,'/api/v1/status');delete snapshot.csrf_token;console.log(JSON.stringify(snapshot,null,2)); }
   else if(command==='doctor') {
     const config=configAt(state);console.log(JSON.stringify({node:process.version,docker:run('docker',['info','--format','{{.ServerVersion}}']),engineInstalled:existsSync(join(state,'engine.json')),repo:config.repo,agent:config.agent,checksConfigured:!!config.check?.trim(),inference:'Not called or verified',dashboard:`http://127.0.0.1:${config.port}`},null,2));
@@ -175,7 +186,7 @@ try {
       run('git',['-C',repo,'-c','user.name=Factory demo','-c','user.email=demo@localhost','commit','-m','Synthetic fixture']);
       init(repo,'mock',"test \"$(cat value.txt)\" = fixed",Number(flags.port || 7332));
     } else if(configAt(state).agent!=='mock')throw new Error('Demo requires a mock configuration');
-    await install();await up();console.log(JSON.stringify(await submit('software','Synthetic installation qualification: fix value.txt. No inference is used.')));
+    await withServiceOperation('demo startup',async()=>{await install();await up();});console.log(JSON.stringify(await submit('software','Synthetic installation qualification: fix value.txt. No inference is used.')));
     console.log('Review the synthetic change in the dashboard and approve its handoff.');
   } else if(['version','--version','-v'].includes(command))console.log(VERSION);
   else if(command==='qualify') {
@@ -183,7 +194,7 @@ try {
   } else if(command==='kit') {
     if(!flags.output)throw new Error('kit requires --output NEW_DIRECTORY');
     await stream(process.execPath,[join(ROOT,'scripts/export-kit.mjs'),resolve(flags.output)]);
-  } else if(command==='help')console.log(`Software & Defence Factory ${VERSION} (test release)
+  } else if(['help','--help','-h'].includes(command))console.log(`Software & Defence Factory ${VERSION} (test release)
 
   kit --output NEW_DIRECTORY               Export the portable method without a runtime
   demo                                    Install and run a synthetic sample (no model key)
@@ -191,8 +202,16 @@ try {
   init --repo PATH --agent codex|pi|custom --check "npm ci && npm test"
   install                                 Build the isolated job image; the controller ships with the CLI
   doctor | up | status | stop              Inspect / operate your private installation
-  serve                                   Foreground supervisor for a VPS service
-  service                                 Print a systemd user-service definition
+  serve                                   Foreground supervisor
+  service [print]                         Print a systemd user-service definition
+  service install|start|stop|restart       Manage a Linux user service (--state PATH)
+                                          install accepts --group EXISTING_GROUP
+  service status|logs|uninstall            Diagnose / remove service, preserve private state
+  service update                          Update idle managed controllers, restore on failure
+  service updates --auto on|off|status     Daily idle updates through a systemd timer
+  service resume                          Release a reconciled maintenance reservation
+  tunnel install|start|stop|status|logs|uninstall --host SSH_ALIAS --port PORT
+                                          Persistent loopback SSH tunnel (macOS/Linux)
   run --file task.md | --issue URL         Submit one software vertical slice
   incident --file incident.json            Submit a private, read-only incident draft
   approve JOB_ID | cancel JOB_ID           Review gate / stop this attempt
@@ -205,6 +224,7 @@ Runtime commands accept --state PATH. Default: ${DEFAULT_STATE}
 Demo default: ${DEFAULT_DEMO_STATE}
 The npm CLI keeps state outside the package; updates wait for stopped installations.
 Dashboard binds only to loopback; use SSH for remote access.
-See docs/quickstart.md for inference, hosting, evidence and recovery.`);
+Setup plan: ${join(ROOT, 'docs/setup.md')}
+See docs/quickstart.md for task execution, evidence and recovery.`);
   else throw new Error(`Unknown command: ${command}`);
 } catch(error) {console.error(`Factory: ${error.message}`);process.exitCode=1;}

package/docs/npm.md

@@ -42,7 +42,12 @@ An npm-installed CLI checks npm's `latest` stable release at most once a day
 when invoked. It downloads and activates a newer release when all registered
 installations are stopped and no executor requires reconciliation. It does not
 run a background updater or interrupt a job. Routine `status`, `stop`, `cancel`,
-`serve` and version commands do not initiate automatic downloads.
+`serve`, service/tunnel management, help and version commands do not initiate automatic downloads.
+
+For an always-running Linux installation, opt into the separate managed daily
+timer with `service updates --auto on`. It reserves idle controllers, updates
+and restores their prior running set without interrupting a job. See
+[services](services.md) for installation, maintenance recovery and limitations.
 
 ```sh
 software-defence-factory update --check

package/docs/quickstart.md

@@ -1,5 +1,7 @@
 # Runtime quickstart
 
+For a new worker or remote operator, start with the [setup plan](setup.md).
+
 Install Node 22.13+, Git and Docker Engine/Desktop. Use an unprivileged account with Docker access. Install `software-defence-factory` through npm, or invoke the same package with npx. No factory source checkout is required.
 
 ## Qualify a synthetic installation
@@ -55,7 +57,7 @@ ssh -N -L 127.0.0.1:7331:127.0.0.1:7331 your-host
 
 Open http://127.0.0.1:7331 on the client. Use the same local/remote port because the HTTP service validates its Host header. The SSH connection must remain open. Access also works across different networks when your configured private network connects the hosts.
 
-Use `status`, `cancel JOB_ID`, `retry JOB_ID` and `stop`, always with the selected `--state`. `service` prints a systemd user-service definition; review and install it through the host's normal service management. It is not enabled by printing it. See [recovery](recovery.md).
+Use `status`, `cancel JOB_ID`, `retry JOB_ID` and `stop`, always with the selected `--state`. `service install --state PATH` installs and enables the supported Linux user service; `service status`, `service logs` and `service uninstall` operate it. Bare `service` only prints a definition. For managed startup, persistent SSH tunnels and daily idle updates, follow [services](services.md). See [recovery](recovery.md) for interrupted attempts.
 
 ## Native application builds
 

package/docs/recovery.md

@@ -0,0 +1,23 @@
+# Recovery and retained evidence
+
+Use `status --state PATH` and the private supervisor.log to identify the active installation. Stop it before replacing its package or container image.
+
+- A normal `stop` signals the controller, waits for the executor process group, removes its labelled containers and retains the database and artifacts.
+- An unconfirmed running attempt becomes `interrupted` on controller restart. It is never silently considered successful.
+- `retry JOB_ID` reconciles the previous process group and containers. A live or unknown writer blocks retry. For a new build/defence attempt, the prior checkout is retained as previous-checkout-*.
+- A failed verification can retry the same unchanged candidate after the check environment is repaired. A changed candidate needs a fresh verification/review sequence.
+- A requested revision retains previous evidence and starts a new build from the source repository with the accumulated feedback. It does not reuse earlier approval.
+- Removing a stopped task from the dashboard hides its queue record. Private artifacts and its deleted_at record remain on disk; this is not secure erasure.
+
+Do not remove active.json merely to unblock a job. Establish that its PID, process group and labelled containers are stopped. PID reuse or missing process identity requires operator investigation. Preserve logs and work before cleanup.
+
+For backup, stop the installation and copy the complete private state directory, including SQLite files, factory.json and credentials, to an authorized private destination. Restore only while stopped. Update the repository path if it moved, verify ownership/permissions and the pinned image, then inspect state before any retry. Keep previous backups; no automatic destructive schema migration is provided.
+
+Earlier experimental engines use a different journal. Start a new state directory for the native 0.3 runtime; preserve old journals separately. There is no automatic import of their jobs or approval state.
+
+Verification cleanup makes owned scratch directories traversable before removing
+them and never follows their symlinks. It runs only after container stop is
+confirmed. If a filesystem error still prevents cleanup, the attempt fails and
+retains the original check exit and private log path alongside the cleanup error.
+Inspect that retained attempt before manual removal; never substitute the source
+candidate path for the scratch path.

package/docs/services.md

@@ -0,0 +1,156 @@
+# Persistent controllers and remote dashboards
+
+For the complete host-to-application sequence and reboot checklist, start with
+[the setup plan](setup.md). Install the npm CLI first. A Factory controller is a Linux systemd **user**
+service; SSH tunnels support Linux systemd and macOS launchd. Neither needs a
+root controller. macOS can still run a local controller with `up`.
+
+## Linux controller
+
+Configure and install a runtime using the [quickstart](quickstart.md), then:
+
+```sh
+software-defence-factory stop --state /absolute/private/state
+software-defence-factory service install --state /absolute/private/state
+software-defence-factory service status --state /absolute/private/state
+```
+
+Installation enables and starts exactly this controller. It does not submit a
+new task. Existing queued jobs will execute when any controller starts; inspect
+the queue before adopting an installation. Interrupted attempts still require
+the normal explicit reconciliation/retry. To keep a product paused, leave its
+controller stopped and do not install a service for it.
+
+The current user must have Docker access; Docker itself must be enabled at boot.
+The CLI records the current PATH, Node executable and private state/data homes.
+The launcher and installed runtime are retained outside the npm/npx cache.
+Removing a Node installation referenced by the service still breaks startup:
+reinstall the service using the intended Node executable after stopping it.
+No credentials are copied into the unit or job containers.
+Each service uses an immutable launcher for its installation version. Installing
+another controller or enabling a timer cannot rewrite an existing launcher's
+base. An explicit managed update controls subsequent release selection in
+`service-release.json`. The separate ordinary CLI `updates.json` preference
+cannot move an existing service to another release, even while all services
+are stopped.
+
+If Docker group membership was added after the user service manager started,
+an SSH shell may have access while user services still get permission denied.
+Refresh the login session at a suitable time, or install with the explicit
+`service install --group docker --state PATH` option. This uses `sg` or a
+command-capable util-linux `newgrp` to apply a group the user **already belongs
+to**. It grants no new membership, needs no sudo and keeps the controller's user
+identity. The group launcher is checked for support before installation.
+
+For boot **without logging in**, an administrator must enable user lingering:
+
+```sh
+sudo loginctl enable-linger USERNAME
+```
+
+`service status` reports lingering, boot versus login startup, service enablement
+and actual HTTP health separately. The CLI never silently grants sudo access or
+changes system-wide Docker, firewall or login configuration. Systemd retries
+startup every 15 seconds if Docker or the configured image is unavailable.
+
+```sh
+software-defence-factory service stop --state /absolute/private/state
+software-defence-factory service start --state /absolute/private/state
+software-defence-factory service restart --state /absolute/private/state
+software-defence-factory service logs --state /absolute/private/state
+software-defence-factory service uninstall --state /absolute/private/state
+```
+
+`up` and `stop` detect a managed installation and use its service manager, so a
+stop does not immediately respawn a second controller. An explicit stop/restart
+may interrupt a job; use it deliberately. `stop` leaves boot enablement in place.
+`uninstall` disables and removes only the registered service definition. It
+preserves the database, credentials, artifacts, retained runtimes and history.
+Repeated installation/removal is safe. Edited/unregistered service definitions
+are refused rather than overwritten. Bare `service` (or `service print`) retains
+the original print-only systemd-unit interface.
+
+## Persistent SSH tunnel on the client
+
+First establish key authentication and a verified host key using normal SSH.
+The remote dashboard must bind to loopback and the machines must be reachable
+(for example through an existing private VPN). Use a configured SSH alias:
+
+```sh
+software-defence-factory tunnel install --host worker --port 7345
+software-defence-factory tunnel status --host worker --port 7345
+software-defence-factory tunnel logs --host worker --port 7345
+software-defence-factory tunnel stop --host worker --port 7345
+software-defence-factory tunnel start --host worker --port 7345
+software-defence-factory tunnel uninstall --host worker --port 7345
+```
+
+Visit `http://127.0.0.1:7345`. The local and remote ports are intentionally equal
+to preserve the dashboard's Host/Origin protection. The tunnel uses only
+loopback addresses, strict host-key checking and noninteractive authentication.
+It exits on forwarding failure, detects dead connections and restarts through
+the OS service manager. It never disables SSH checks or requests a password.
+Stop an existing manual tunnel before installation; occupied ports are refused.
+
+On macOS this is a LaunchAgent: it starts at **login**, not before FileVault is
+unlocked. On Linux, lingering determines boot versus login startup. A sleeping
+or offline peer is still unavailable; the tunnel reconnects when connectivity
+returns. Tailscale/SSH/system power configuration remains machine infrastructure,
+not a Factory network dependency. No root LaunchDaemon is installed.
+
+## Updating an always-running controller
+
+```sh
+software-defence-factory service update
+software-defence-factory service updates --auto on
+software-defence-factory service updates --auto status
+software-defence-factory service updates --auto off
+```
+
+`service update` manages all registered controllers for the current user. It
+refuses unmanaged live controllers or unresolved executor fences. Every running
+controller must atomically accept an idle maintenance reservation: queued work,
+an active phase or a concurrent action defers the update. A reservation blocks
+new tasks and actions and persists across restarts until explicitly released.
+Downloads are immutable. Only the previously running managed controllers are
+stopped and restarted; intentionally stopped projects stay stopped. HTTP health
+must recover. A failed release startup restores the prior selection and starts
+the old services before releasing maintenance. Images and application code are
+never rebuilt or silently changed by this operation.
+Lifecycle changes and updates share an exclusive operation lock. Concurrent
+start/stop/install/uninstall commands fail clearly rather than undoing an update
+or an operator's stop. A managed installation refuses ordinary foreground
+`serve`; operate it through `service start`. Stop also checks for a remaining
+controller outside the service before reporting success. Restart health must
+report the expected runtime version, including during rollback.
+
+The opt-in Linux timer checks daily, including a catch-up after downtime, with
+up to one hour of random delay. A busy/unavailable installation causes a failed
+attempt and remains unchanged; the next scheduled invocation retries. Inspect
+`journalctl --user -u software-defence-factory-update.service`. This timer is
+separate from `update --auto on|off`, which controls ordinary CLI invocations.
+Remove the timer with `service updates --auto off` when retiring this setup.
+
+## Recovery and proof limits
+
+If a service operation is killed or the machine loses power, inspect
+`STATE_HOME/software-defence-factory/service-update.lock`, its PID and the
+service logs. The lock records the owning PID and action. Do not remove a lock belonging to a live or unknown process.
+After confirming the updater stopped, remove that stale lock, inspect the
+selected release and start/verify each prior service. Then release each remaining
+reservation using `service resume --state PATH`. There is no automatic timeout
+that might reopen a queue while an updater is still working.
+
+If a generated service was edited outside the CLI, preserve the edit and
+reconcile its recorded definition before using lifecycle commands. A service
+health failure leaves installation and logs in place for diagnosis. Keep the
+prior release, private state and pinned image; see [recovery](recovery.md).
+
+Service enablement and process-restart tests are not proof of a full machine
+reboot, pre-login disk availability or connectivity across two physical networks.
+Record those observations separately. A healthy dashboard proves neither model
+quality nor that a product agent should start.
+
+References: [systemd service semantics](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html),
+[loginctl lingering](https://www.freedesktop.org/software/systemd/man/latest/loginctl.html),
+[Apple launchd definitions](https://github.com/apple-oss-distributions/launchd/blob/main/man/launchd.plist.5).

package/docs/setup.md

@@ -0,0 +1,235 @@
+# Setup plan: operator, worker and application
+
+Use this plan for a new installation or when moving an existing Factory to a
+worker machine. Complete the applicable checkpoints in order and record the
+result in a **private** copy of the checklist below. The plan applies to any
+operator/worker names and any suitable private network; it requires no personal
+context system, particular VPN provider or Factory source checkout.
+
+The operator owns access and infrastructure choices. Factory maintainers own
+this plan and the linked command guides and update them with behavior changes.
+Paths beginning `/private/state` or `/absolute/path` below are placeholders;
+replace them with user-owned absolute directories outside the application and
+installed package.
+
+## 1. Choose the scope and hosts
+
+| Choice | Record before installation |
+| --- | --- |
+| Method only or runtime | Method export needs no Docker, background service or model |
+| Operator/client | Local machine, user and how the dashboard will be opened |
+| Worker | Linux/systemd for managed controllers; macOS can use manual `up` |
+| Applications | Canonical repository, branch, preserved WIP and responsible owner |
+| Runtime | Stable Node executable (22.13+), Git, Docker, CPU/RAM/disk budget |
+| State | Private state path and unused loopback port for each installation |
+| Inference | Provider/model, credential reference, job image and network path |
+| Automation | Which controllers may start, update policy and who may submit work |
+| Recovery | Private backup location, retained runtime/image and recovery contact |
+
+One installation owns one repository and port. A synthetic qualification
+installation can provide a running dashboard while product controllers remain
+stopped. There is no multi-project controller or second scheduler hidden in
+this plan. Keep unrelated personal agent configuration on its existing host.
+
+For method-only adoption, run `software-defence-factory kit --output NEW_DIRECTORY`
+and follow [the adoption guide](../kit/README.md). The remaining host/runtime
+steps apply only when using Factory's optional controller.
+
+## 2. Establish host access and boot prerequisites
+
+Use an unprivileged operator account. Check `node --version`, `git --version`
+and `docker info` from the actual login/SSH session. Install dependencies using
+the host's supported method. For a Linux worker, Docker, SSH and any private
+network client must start at boot; inspect their actual unit names instead of
+assuming every distribution uses the same service names.
+
+For remote access:
+
+1. Establish a reachable private address, including across networks if needed.
+2. Enroll the worker's verified SSH host key and configure key authentication.
+3. Create an SSH alias such as `factory-worker`; verify
+   `ssh -o BatchMode=yes factory-worker 'id -un'` from the operator machine.
+4. Verify firewall/interface scope. Keep the dashboard on loopback; do not
+   expose it publicly or disable host-key checking to make the tunnel work.
+
+Administrator access is a separate host choice. Installing/running Factory user
+services does **not** require root or unrestricted passwordless sudo. If the
+owner deliberately chooses passwordless administration, inspect `sudo -n -l`
+for the intended `NOPASSWD` policy and repeat the permitted command after a
+fresh reboot. A successful `sudo -n` command can merely reuse cached
+credentials. A missing rule must be installed by an authenticated administrator;
+record that remaining step without blocking unprivileged Factory operation.
+
+Record disk unlock, login and power behavior explicitly. Linux user lingering
+can start services without desktop login **after the OS and home are available**;
+it cannot unlock an encrypted disk. A sleeping laptop is not an available
+worker. Choose AC/battery/sleep behavior with the owner; do not disable disk
+security or change power policy as a side effect of Factory setup.
+
+Checkpoint: noninteractive SSH (when needed), Docker and the chosen Node binary
+work, and required host dependencies have a documented startup/recovery owner.
+
+## 3. Install the package and qualify the runtime
+
+```sh
+npm install --global software-defence-factory
+software-defence-factory --version
+software-defence-factory help
+```
+
+Use a user-writable npm prefix or the existing Node manager; do not turn the
+controller into a root process to work around installation permissions. For
+example, Linux users choosing `--prefix "$HOME/.local"` must also make
+`$HOME/.local/bin` available in their login PATH. `npx` uses the same package;
+managed services retain a runtime outside its cache. Keep the service's recorded
+Node executable available. See [installation and updates](npm.md).
+
+Use a **separate synthetic state and unused port** to exercise the runtime:
+
+```sh
+software-defence-factory demo --state /private/state/runtime-proof --port 7345
+# Inspect and finish the sample handoff before qualification.
+software-defence-factory qualify --state /private/state/runtime-proof
+```
+
+These commands deliberately create synthetic jobs, including failed/interrupted
+attempts. Never use application state for `demo` or `qualify`. They make no model
+calls and prove neither model quality nor application readiness. Preserve the
+qualification record; stop this controller unless it is the selected dashboard.
+
+## 4. Prepare each application and inference profile
+
+Preserve existing commits, branches, uncommitted work and licenses before moving
+anything. Verify the canonical GitHub origin and main branch's tracking target;
+a fork may still track its upstream product. Move application sources into the
+chosen workspace, not into the npm package or private runtime state.
+
+Before admitting development work, establish:
+
+- Reproducible toolchain/dependency pins and an actual build/check command.
+- A compatible job image for native libraries, browser/mobile tools or custom
+  model adapters; the standard image does not supply every application stack.
+- Meaningful checks in GitHub CI on the selected revision, plus the intended
+  review/branch policy. Record plan/access limits if enforcement is unavailable.
+- Applicable application instructions, design/scope, resource limits, secret
+  references and a clear delivery destination. Keep unfinished WIP separate
+  until intentionally integrated; jobs clone committed source only.
+
+Configure a new installation using [the quickstart](quickstart.md):
+
+```sh
+software-defence-factory init --repo /absolute/path/to/app --agent pi --check "npm ci && npm test" --state /private/state/my-app --port 7331
+software-defence-factory install --state /private/state/my-app
+software-defence-factory doctor --state /private/state/my-app
+```
+
+Replace the agent/check/paths with the accepted application profile. `install`
+builds the standard image: do not use it to overwrite an existing custom image
+selection. Follow the application image's own build/pinning procedure instead.
+`init` does not edit the app, install personal skills or submit a task. Runtime
+jobs receive the bundled method and six skills automatically.
+
+For a local model, verify the existing model service, intended model name and
+its startup. Test the model API from a disposable container using the **selected
+job image and network**. Host `127.0.0.1` inside a container is not the host's
+loopback. Any host bridge/proxy and narrow firewall rule are explicit machine
+infrastructure; they need their own startup and reboot checks. A bridge address may appear
+after the user service manager starts; configure retry/readiness and verify
+recovery rather than assuming startup order from enablement alone. Avoid duplicate
+model servers, public listeners, Docker socket mounts or whole account folders.
+Cloud inference likewise needs a real provider/model connectivity check without
+printing credentials. A model-list/health response is connectivity evidence;
+qualifying model output requires a separately accepted bounded task.
+
+Checkpoint: record the exact source revision, image ID, check command, resource
+limits, inference connectivity and CI result. Keep product controllers stopped
+until their tasks are explicitly ready to run.
+
+## 5. Enable only the intended background services
+
+A newly initialized state has no jobs. Before adopting older state, establish
+that its queue may resume; starting **any** controller executes queued work.
+If queue ownership/state is uncertain, reconcile it before enabling autostart.
+
+On the Linux worker, select the state that should stay available:
+
+```sh
+software-defence-factory stop --state /private/state/runtime-proof
+software-defence-factory service install --state /private/state/runtime-proof
+software-defence-factory service status --state /private/state/runtime-proof
+software-defence-factory service updates --auto on
+software-defence-factory service updates --auto status
+```
+
+Follow [services](services.md) for user lingering, existing Docker group
+membership, logs, stop/start, uninstall and maintenance recovery. A user manager
+started before Docker group membership changed may need `--group docker`; this
+applies an existing group and grants no new membership. Enable lingering only
+for the intended account through the host's administrator.
+
+On the operator machine, stop any old manual tunnel, then:
+
+```sh
+software-defence-factory tunnel install --host factory-worker --port 7345
+software-defence-factory tunnel status --host factory-worker --port 7345
+```
+
+Use the actual selected dashboard port on both sides. macOS tunnels start at
+user login; Linux uses its user service manager. Open `http://127.0.0.1:7345`.
+This is the worker's loopback dashboard forwarded through SSH.
+
+Managed daily updates reserve idle controllers and preserve the prior running
+set; they defer when busy and attempt rollback if the new runtime is unhealthy.
+A deliberate `service stop` leaves boot enablement in place: use `uninstall`
+when a controller must also remain disabled across reboots. Preserve private
+state and previous releases. The timer does not rebuild application images,
+start product tasks, change a model or publish application changes.
+
+## 6. Prove reboot recovery and hand over
+
+Choose a reboot window with disk unlock/recovery available. Save a private
+baseline of the boot ID (`cat /proc/sys/kernel/random/boot_id`), runtime version,
+job IDs/states/attempts, selected enabled services and paused installations.
+After the owner reboots/unlocks the worker, check **before manually starting
+anything**:
+
+- SSH returns and a changed boot ID confirms a new boot.
+- Docker, private network and model/proxy services are healthy, with no relevant
+  failed units or repeated restart loop. Inspect their current-boot logs.
+- `service status --state PATH` reports enabled/running/healthy, the intended
+  runtime version and no unexpected maintenance reservation.
+- The update timer is enabled and has a next execution time.
+- The operator's tunnel reconnects and the dashboard responds at the same URL.
+- Job history is unchanged and intentionally disabled product controllers have
+  no listeners or executor processes. Probe model connectivity from the job
+  container again without starting a product agent.
+- The intended administrator policy still works, if that capability was chosen.
+
+Record actual observations and failures separately. An observed boot after
+manual unlock/login does not prove an unattended cold boot; a worker reboot
+does not prove operator-machine login startup. Process crash recovery and tests
+across two physical networks are also distinct checks. Use [recovery](recovery.md)
+and [service recovery](services.md#recovery-and-proof-limits) for failures; do not
+start a second controller or clear unknown process locks to make status green.
+
+Copy this private completion record into the installation's handoff:
+
+| Checkpoint | Result | Evidence / remaining action |
+| --- | --- | --- |
+| Host roles, owner, source and private state selected | Pending | |
+| SSH, Docker, Node and host startup prerequisites | Pending | |
+| Synthetic runtime qualification | Pending | |
+| Application image, real checks/CI and preserved WIP | Pending | |
+| Inference path and chosen model | Pending | |
+| Controller/tunnel/timer installation and recovery | Pending | |
+| Worker reboot after required unlock/login | Pending | |
+| Operator login recovery / separate networks | Pending | Record separately |
+| History and intentionally stopped products preserved | Pending | |
+| Backups, logs, stop/update/rollback owner and guide | Pending | |
+| First bounded application task | Not started | Separate task authority and proof |
+
+Use Pass, Fail or Not applicable with a reason; never infer success from an
+installed file. Keep host identities, credentials, raw logs and customer details
+out of public issues and package contents. A ready worker is only the foundation:
+follow [the method](../kit/README.md#first-real-task) for the first explicitly
+accepted application task and revision-bound checks/review/handoff.

package/factory/queue.mjs

@@ -1,6 +1,7 @@
 import { DatabaseSync } from 'node:sqlite';
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
+import { existsSync, writeFileSync, rmSync } from 'node:fs';
 
 const workflows = { software: ['build', 'verify', 'review', 'handoff'], defence: ['defence'] };
 const id = prefix => prefix + '_' + randomBytes(12).toString('hex');
@@ -14,7 +15,8 @@ export class JobQueue {
     this.db = new DatabaseSync(join(state, 'jobs.sqlite'));
     this.db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; CREATE TABLE IF NOT EXISTS jobs(id TEXT PRIMARY KEY, data TEXT NOT NULL);');
     this.execute = execute; this.stop = stop; this.reconcile = reconcile;
-    this.active = null; this.closing = false; this.pumping = false; this.actions = new Set();
+    this.maintenanceFile = join(state, 'maintenance.json');
+    this.active = null; this.closing = false; this.pumping = false; this.actions = new Set(); this.maintenance = existsSync(this.maintenanceFile);
     for (const job of this.all()) if (['running', 'cancelling'].includes(job.state)) {
       job.state = 'interrupted';
       Object.assign(job.runs.at(-1), { state: 'interrupted', completed_at: now(), error: 'Controller stopped before completion was confirmed.' });
@@ -32,6 +34,7 @@ export class JobQueue {
   save(job) { job.updated_at = now(); this.db.prepare('INSERT INTO jobs VALUES (?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(job.id, JSON.stringify(job)); return job; }
   submit(input) {
     if (this.closing) throw new QueueError('Controller is stopping');
+    if (this.maintenance) throw new QueueError('Controller is reserved for maintenance');
     if (input?.source_url && (typeof input.source_url !== 'string' || !/^https?:\/\/[^\s]+$/.test(input.source_url) || input.source_url.length > 2048)) throw new QueueError('Expected an HTTP(S) source link', 400);
     if (input?.model && (typeof input.model !== 'string' || !/^[\w.:/+-]{1,128}$/.test(input.model))) throw new QueueError('Invalid model identifier', 400);
     if (input?.source_url && !input.spec?.trim()) input = { ...input, spec: `Investigate the linked requirements within this repository's scope: ${input.source_url}` };
@@ -42,10 +45,19 @@ export class JobQueue {
       state: 'queued', created_at: now(), runs: [] };
     this.save(job); this.schedule(); return { id: job.id };
   }
+  setMaintenance(enabled) {
+    if (typeof enabled !== 'boolean') throw new QueueError('Expected enabled: true or false', 400);
+    if (enabled && (this.closing || this.active || this.actions.size || this.all().some(job => ['queued', 'running', 'cancelling'].includes(job.state)))) throw new QueueError('Controller is busy; update deferred');
+    if (enabled) writeFileSync(this.maintenanceFile, JSON.stringify({ startedAt: now() }), { mode: 0o600 });
+    else rmSync(this.maintenanceFile, { force: true });
+    this.maintenance = enabled;
+    if (!enabled) this.schedule();
+    return { maintenance: enabled };
+  }
   schedule() { if (!this.closing && !this.pumping) { this.pumping = true; queueMicrotask(() => this.pump()); } }
   async pump() {
     try {
-      while (!this.closing) {
+      while (!this.closing && !this.maintenance) {
         let job = this.all().find(item => item.state === 'queued'); if (!job) break;
         const step = job.workflow.current_step, phase = job.workflow.steps[step];
         let attempt = job.runs.at(-1);
@@ -77,7 +89,7 @@ export class JobQueue {
     } finally { this.pumping = false; }
   }
   async exclusive(jobId, perform) {
-    if (this.closing || this.actions.has(jobId)) throw new QueueError('Job is already changing; reload before acting');
+    if (this.closing || this.maintenance || this.actions.has(jobId)) throw new QueueError('Job is already changing or controller is reserved for maintenance; reload before acting');
     this.actions.add(jobId);
     try { return await perform(); } finally { this.actions.delete(jobId); }
   }

package/factory/server.mjs

@@ -6,6 +6,7 @@ import { hostname } from 'node:os';
 import { JobQueue, QueueError } from './queue.mjs';
 import { executors } from './processes.mjs';
 import { configAt, ROOT } from './lib.mjs';
+import { VERSION } from './updates.mjs';
 
 function equal(a, b) { return typeof a === 'string' && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b)); }
 async function body(request) {
@@ -42,7 +43,7 @@ export function createController(state, adapter = executors(state)) {
           outcome: attempt.outcome || (attempt.state === 'succeeded' ? 'complete' : undefined),
           executor: ['verify','handoff'].includes(attempt.command) ? 'deterministic' : config.agent,
           worker_name: hostname(), model: job.model || config.model })) }));
-        return send(200, { version: 1, workflows: ['software', 'defence'], commands: [], triggers: [], jobs, csrf_token: csrf,
+        return send(200, { version: 1, runtime_version: VERSION, maintenance: queue.maintenance, workflows: ['software', 'defence'], commands: [], triggers: [], jobs, csrf_token: csrf,
           workers: [{ name: hostname(), instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }],
           repositories: ['app'], repo: config.repo, agent: config.agent });
       }
@@ -73,6 +74,10 @@ export function createController(state, adapter = executors(state)) {
         if (!authenticated) throw new QueueError('Session required', 403);
         if (!(request.headers['content-type'] || '').startsWith('application/json')) throw new QueueError('Use application/json', 415);
         const input = await body(request);
+        if (url.pathname === '/api/v1/maintenance') {
+          if (!equal(request.headers.authorization, `Bearer ${token}`)) throw new QueueError('Operator token required for maintenance', 403);
+          return send(200, queue.setMaintenance(input.enabled));
+        }
         if (url.pathname === '/api/v1/jobs') {
           if (input.model && input.model !== config.model && !['codex','pi'].includes(config.agent)) throw new QueueError('Model overrides require a codex or pi executor', 400);
           return send(201, queue.submit(input));

package/factory/service-files.mjs

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+export function serviceId(kind, identity) {
+  return `software-defence-factory-${kind}-${createHash('sha256').update(identity).digest('hex').slice(0, 16)}`;
+}
+function text(value) {
+  if (typeof value !== 'string' || /[\x00-\x1f\x7f]/.test(value)) throw new Error('Service values cannot contain control characters');
+  return value;
+}
+const unit = value => JSON.stringify(text(value).replaceAll('%', '%%'));
+const argument = value => unit(value.replaceAll('$', () => '$$'));
+const xml = value => text(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+
+export function systemdUnit({ description, argv, directory, environment = {}, oneshot = false }) {
+  return `[Unit]\nDescription=${text(description)}\nStartLimitIntervalSec=0\n\n[Service]\nType=${oneshot ? 'oneshot' : 'exec'}\nWorkingDirectory=${text(directory).replaceAll('%', '%%')}\nExecStart=${argv.map(argument).join(' ')}\n${Object.entries(environment).map(([key, value]) => {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) throw new Error('Invalid environment name');
+    return `Environment=${unit(`${key}=${value}`)}\n`;
+  }).join('')}${oneshot ? 'TimeoutStartSec=15min\n' : 'Restart=always\nRestartSec=15\n'}TimeoutStopSec=60\nKillMode=control-group\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`;
+}
+export function launchAgent({ id, argv, directory, log, environment = {} }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${xml(id)}</string>\n<key>ProgramArguments</key><array>${argv.map(value => `<string>${xml(value)}</string>`).join('')}</array>\n<key>WorkingDirectory</key><string>${xml(directory)}</string>\n<key>EnvironmentVariables</key><dict>${Object.entries(environment).map(([key, value]) => `<key>${xml(key)}</key><string>${xml(value)}</string>`).join('')}</dict>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>\n<key>ThrottleInterval</key><integer>15</integer>\n<key>ExitTimeOut</key><integer>60</integer>\n<key>Umask</key><integer>63</integer>\n<key>StandardOutPath</key><string>${xml(log)}</string>\n<key>StandardErrorPath</key><string>${xml(log)}</string>\n</dict></plist>\n`;
+}
+export function tunnelArguments(host, port) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.@-]*$/.test(host || '')) throw new Error('Use an SSH hostname or configured alias without spaces or options');
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Tunnel port must be 1024–65535');
+  return ['/usr/bin/ssh', '-N', '-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ExitOnForwardFailure=yes',
+    '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=15', '-o', 'ServerAliveCountMax=3', '-L', `127.0.0.1:${port}:127.0.0.1:${port}`, host];
+}
+export function groupArguments(argv, group, executable) {
+  if (!/^[a-z_][a-z0-9_-]*[$]?$/.test(group || '')) throw new Error('Expected an existing Unix group name');
+  if (!['/usr/bin/sg', '/usr/bin/newgrp'].includes(executable)) throw new Error('Unsupported group launcher');
+  const quote = value => `'${text(value).replaceAll("'", "'\\''")}'`;
+  return [executable, group, '-c', 'exec ' + argv.map(quote).join(' ')];
+}
+
+// Immutable launcher: ordinary CLI preferences never select a service release.
+export function runtimeLauncher({ runtime, stateHome, dataHome }) {
+  return `import { readFileSync, existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nlet root = ${JSON.stringify(runtime)};\nconst settings = ${JSON.stringify(join(stateHome, 'service-release.json'))};\nif (existsSync(settings)) {\n  const version = JSON.parse(readFileSync(settings, 'utf8')).version;\n  if (/^\\d+\\.\\d+\\.\\d+$/.test(version || '')) {\n    const candidate = join(${JSON.stringify(dataHome)}, 'releases', version, 'node_modules/software-defence-factory');\n    if (existsSync(join(candidate, 'package.json'))) {\n      const pkg = JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8'));\n      const current = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;\n      const a = version.split('.').map(Number), b = current.split('.').map(Number);\n      const index = a.findIndex((value, i) => value !== b[i]);\n      if (pkg.name === 'software-defence-factory' && pkg.version === version && index >= 0 && a[index] > b[index]) root = candidate;\n    }\n  }\n}\nprocess.env.SDF_AUTO_UPDATE = '0';\nprocess.env.SDF_BOOTSTRAPPED = '1';\nawait import(pathToFileURL(join(root, 'bin/software-defence-factory.mjs')).href);\n`;
+}

package/factory/services.mjs

@@ -0,0 +1,298 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, cpSync, readdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir, userInfo } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { ROOT, STATE_HOME, DATA_HOME, SOURCE_CHECKOUT } from './paths.mjs';
+import { configAt, json, save, run, api, sleep, digest } from './lib.mjs';
+import { VERSION, newer, latestVersion, installRelease, busyInstallations } from './updates.mjs';
+import { serviceId, systemdUnit, launchAgent, tunnelArguments, groupArguments, runtimeLauncher } from './service-files.mjs';
+
+const records = join(STATE_HOME, 'services');
+const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+const userUnits = join(configHome, 'systemd/user');
+const updater = 'software-defence-factory-update';
+const recordPath = id => join(records, `${id}.json`);
+const systemctl = (...args) => run('systemctl', ['--user', ...args]);
+const uid = () => process.getuid();
+function userOnly() { if (uid() === 0) throw new Error('Install and operate user services without sudo; never run the controller as root'); }
+function alive(pid) { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; throw error; } }
+export const controllerService = state => recordPath(serviceId('controller', state));
+export function hasService(state) { return existsSync(controllerService(state)); }
+export async function withServiceOperation(action, perform) {
+  const lock = join(STATE_HOME, 'service-update.lock');
+  mkdirSync(STATE_HOME, { recursive: true, mode: 0o700 });
+  try { writeFileSync(lock, JSON.stringify({ pid: process.pid, action }), { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error(`Another service operation may own ${lock}; reconcile its PID before removing the lock`); throw error; }
+  try { return await perform(); } finally { rmSync(lock); }
+}
+export function isManagedLaunch(state) {
+  return hasService(state) && process.env.SDF_MANAGED_SERVICE === serviceId('controller', state);
+}
+function owned(record) {
+  if (!existsSync(record.file) || digest(readFileSync(record.file, 'utf8')) !== record.definitionHash) throw new Error(`Service definition changed outside the CLI; reconcile ${record.file} before changing it`);
+}
+function loaded(record) {
+  if (record.platform === 'linux') return systemctl('show', record.unit, '--property=LoadState', '--value') !== 'not-found';
+  const result = spawnSync('/bin/launchctl', ['print', `gui/${uid()}/${record.id}`], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status === 0) return true;
+  if (/Could not find service|Could not find specified service/.test(result.stderr)) return false;
+  throw new Error(result.stderr || 'Cannot inspect launchd service');
+}
+function active(record) {
+  if (record.platform === 'linux') return ['active', 'activating', 'reloading'].includes(systemctl('show', record.unit, '--property=ActiveState', '--value'));
+  return loaded(record);
+}
+function start(record) {
+  owned(record);
+  if (record.platform === 'linux') systemctl('start', record.unit);
+  else if (!loaded(record)) run('/bin/launchctl', ['bootstrap', `gui/${uid()}`, record.file]);
+}
+function stop(record) {
+  owned(record);
+  if (record.platform === 'linux') { if (active(record)) systemctl('stop', record.unit); }
+  else if (loaded(record)) run('/bin/launchctl', ['bootout', `gui/${uid()}/${record.id}`]);
+  if (record.kind === 'controller') {
+    const lock = join(record.state, 'supervisor.json');
+    if (existsSync(lock) && alive(json(lock).pid)) throw new Error('A controller remains alive outside the stopped service; reconcile its supervisor PID before proceeding');
+  }
+}
+export async function waitHealthy(record, expectedVersion) {
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    try {
+      if (record.kind === 'controller') {
+        const status = await api(record.state, '/api/v1/status');
+        if (status.workers?.some(worker => worker.connected) && (!expectedVersion || status.runtime_version === expectedVersion)) return status;
+      } else {
+        const response = await fetch(`http://127.0.0.1:${record.port}/api/v1/status`, { signal: AbortSignal.timeout(1000) });
+        if (response.ok && (await response.json()).workers) return;
+      }
+    } catch { /* A service may be waiting for Docker or the SSH peer. */ }
+    await sleep(500);
+  }
+  throw new Error(`Service is installed but dashboard is not ready; inspect ${record.file} and service logs. It will keep retrying.`);
+}
+async function portFree(port) {
+  await new Promise((resolve, reject) => {
+    const server = createServer(); server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => server.close(resolve));
+  });
+}
+// Retain only installed package content. A source tree or npx cache is never
+// the service's enduring runtime. Old snapshots remain available for recovery.
+function retainRuntime() {
+  if (SOURCE_CHECKOUT) throw new Error('Install the npm artifact before installing a service; source worktrees are not service runtimes');
+  const destination = join(DATA_HOME, 'services/runtimes', VERSION);
+  if (!existsSync(destination)) {
+    mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+    const staging = `${destination}.${process.pid}.tmp`;
+    try {
+      mkdirSync(staging, { mode: 0o700 });
+      for (const name of ['package.json', 'bin', 'factory', 'kit', '.agents', 'scripts']) if (existsSync(join(ROOT, name))) cpSync(join(ROOT, name), join(staging, name), { recursive: true });
+      renameSync(staging, destination);
+    } finally { rmSync(staging, { recursive: true, force: true }); }
+  }
+  if (json(join(destination, 'package.json')).version !== VERSION) throw new Error('Retained service runtime identity mismatch');
+  return destination;
+}
+function launcher() {
+  const runtime = retainRuntime(), file = join(DATA_HOME, 'services', `launch-${VERSION}-${digest(STATE_HOME).slice(0, 16)}.mjs`);
+  const content = runtimeLauncher({ runtime, stateHome: STATE_HOME, dataHome: DATA_HOME });
+  if (existsSync(file)) {
+    if (readFileSync(file, 'utf8') !== content) throw new Error('Retained launcher content differs; preserve and reconcile it before installation');
+  } else writeFileSync(file, content, { flag: 'wx', mode: 0o600 });
+  return file;
+}
+function environment() {
+  return { PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin', HOME: homedir(), XDG_STATE_HOME: dirname(STATE_HOME), XDG_DATA_HOME: dirname(DATA_HOME), XDG_CONFIG_HOME: configHome, SDF_AUTO_UPDATE: '0' };
+}
+export function serviceDefinition(state) {
+  configAt(state);
+  return systemdUnit({ description: 'Software & Defence Factory', argv: [process.execPath, join(ROOT, 'bin/software-defence-factory.mjs'), 'serve', '--state', state], directory: homedir(), environment: environment() });
+}
+async function install(kind, state, flags) {
+  userOnly();
+  if (kind === 'controller' && process.platform !== 'linux') throw new Error('Controller services currently require Linux/systemd; use up on macOS. Tunnel services support macOS and Linux.');
+  if (!['linux', 'darwin'].includes(process.platform)) throw new Error('Services require Linux/systemd or macOS/launchd');
+  const port = kind === 'controller' ? configAt(state).port : Number(flags.port);
+  const id = kind === 'controller' ? serviceId(kind, state) : serviceId(kind, `${flags.host}:${port}`);
+  if (existsSync(recordPath(id))) {
+    const previous = json(recordPath(id)); owned(previous);
+    if (kind === 'controller' && previous.state !== state) throw new Error('Service identity mismatch');
+    if (previous.port !== port || (flags.group && previous.group !== flags.group)) throw new Error('Service configuration changed; uninstall and reinstall the service while preserving its private state');
+    if (previous.platform === 'linux') systemctl('enable', previous.unit);
+    start(previous); await waitHealthy(previous);
+    console.log(JSON.stringify(await serviceStatus(previous), null, 2)); return;
+  }
+  if (kind === 'controller') {
+    if (!existsSync(join(state, 'engine.json'))) throw new Error('Run install for this state before installing its service');
+    if (existsSync(join(state, 'supervisor.json')) && alive(json(join(state, 'supervisor.json')).pid)) throw new Error('Stop the manually started controller before adopting it as a service');
+    run('docker', ['image', 'inspect', configAt(state).image]);
+  }
+  let argv = kind === 'controller' ? [process.execPath, launcher(), 'serve', '--state', state] : tunnelArguments(flags.host, port);
+  if (flags.group) {
+    if (kind !== 'controller') throw new Error('--group applies only to Linux controller services');
+    if (!run('id', ['-nG', userInfo().username]).split(/\s+/).includes(flags.group)) throw new Error('The current user must already belong to the requested group');
+    const executable = existsSync('/usr/bin/sg') ? '/usr/bin/sg' : '/usr/bin/newgrp';
+    if (executable.endsWith('/newgrp') && !run(executable, ['--help']).includes('--command')) throw new Error('This newgrp does not support commands; use a system with sg or refresh the login session');
+    argv = groupArguments(argv, flags.group, executable);
+  }
+  await portFree(port);
+  const record = { id, kind, platform: process.platform, version: VERSION, port, state: kind === 'controller' ? state : undefined, host: flags.host, group: flags.group, argv, environment: environment() };
+  if (kind === 'controller') record.environment.SDF_MANAGED_SERVICE = id;
+  record.unit = `${id}.service`;
+  record.file = process.platform === 'linux' ? join(userUnits, record.unit) : join(homedir(), 'Library/LaunchAgents', `${id}.plist`);
+  record.log = join(records, `${id}.log`);
+  const definition = process.platform === 'linux' ? systemdUnit({ description: `Software & Defence Factory ${kind}`, argv, directory: homedir(), environment: record.environment })
+    : launchAgent({ id, argv, directory: homedir(), log: record.log, environment: record.environment });
+  if (existsSync(record.file)) throw new Error(`Refusing to overwrite an unregistered service: ${record.file}`);
+  mkdirSync(dirname(record.file), { recursive: true, mode: 0o700 }); mkdirSync(records, { recursive: true, mode: 0o700 });
+  writeFileSync(record.file, definition, { mode: 0o600 }); record.definitionHash = digest(definition); save(recordPath(id), record);
+  if (process.platform === 'linux') { run('systemd-analyze', ['--user', 'verify', record.file]); systemctl('daemon-reload'); systemctl('enable', record.unit); }
+  start(record);
+  await waitHealthy(record);
+  console.log(JSON.stringify(await serviceStatus(record), null, 2));
+}
+async function serviceStatus(record) {
+  owned(record);
+  const result = { id: record.id, kind: record.kind, definition: record.file, dashboard: `http://127.0.0.1:${record.port}`, running: active(record) };
+  if (record.platform === 'linux') {
+    result.enabled = systemctl('show', record.unit, '--property=UnitFileState', '--value') === 'enabled';
+    const linger = run('loginctl', ['show-user', userInfo().username, '-p', 'Linger', '--value']);
+    result.linger = linger === 'yes'; result.startsAt = result.linger ? 'boot' : 'login';
+    if (!result.linger) result.next = `For boot without login, an administrator can run: loginctl enable-linger ${userInfo().username}`;
+    result.logs = `journalctl --user -u ${record.unit} -n 100 --no-pager`;
+  } else { result.startsAt = 'login'; result.logs = record.log; }
+  try {
+    const response = await fetch(`http://127.0.0.1:${record.port}/api/v1/status`, { signal: AbortSignal.timeout(1500) });
+    const snapshot = await response.json(); result.healthy = response.ok && !!snapshot.workers;
+    result.runtimeVersion = snapshot.runtime_version; result.maintenance = snapshot.maintenance;
+  }
+  catch { result.healthy = false; }
+  return result;
+}
+export async function manageService(kind, action, state, flags = {}) {
+  userOnly();
+  if (kind === 'tunnel') tunnelArguments(flags.host, Number(flags.port));
+  if (kind === 'controller' && action === 'update') return updateServices();
+  const readonly = ['status', 'logs'].includes(action) || (action === 'updates' && flags.auto === 'status');
+  return readonly ? performService(kind, action, state, flags) : withServiceOperation(`${kind} ${action}`, () => performService(kind, action, state, flags));
+}
+async function performService(kind, action, state, flags) {
+  if (kind === 'controller' && action === 'updates') return automaticUpdates(flags.auto);
+  if (kind === 'controller' && action === 'resume') {
+    console.log(JSON.stringify(await api(state, '/api/v1/maintenance', { enabled: false }))); return;
+  }
+  if (action === 'install') return install(kind, state, flags);
+  const id = kind === 'controller' ? serviceId(kind, state) : serviceId(kind, `${flags.host}:${Number(flags.port)}`);
+  if (!['start', 'stop', 'restart', 'status', 'uninstall', 'logs'].includes(action)) throw new Error('Use service/tunnel install|start|stop|restart|status|logs|uninstall; service update; service updates --auto on|off|status');
+  if (!existsSync(recordPath(id))) {
+    if (action === 'status') { console.log(JSON.stringify({ installed: false, id })); return; }
+    if (action === 'uninstall') { console.log('Service is already uninstalled; private state was preserved.'); return; }
+    throw new Error('Service is not installed');
+  }
+  const record = json(recordPath(id)); owned(record);
+  if (action === 'status') { console.log(JSON.stringify(await serviceStatus(record), null, 2)); return; }
+  if (action === 'logs') {
+    console.log(record.platform === 'linux' ? run('journalctl', ['--user', '-u', record.unit, '-n', '100', '--no-pager']) : (existsSync(record.log) ? readFileSync(record.log, 'utf8').split('\n').slice(-100).join('\n') : 'No service log yet.')); return;
+  }
+  if (['stop', 'restart', 'uninstall'].includes(action)) stop(record);
+  if (['start', 'restart'].includes(action)) { start(record); await waitHealthy(record); }
+  if (action === 'uninstall') {
+    if (record.platform === 'linux') systemctl('disable', record.unit);
+    rmSync(record.file); rmSync(recordPath(id));
+    if (record.platform === 'linux') systemctl('daemon-reload');
+  }
+  console.log(`${action}: ${id}. Private state and retained runtimes were preserved.`);
+}
+
+function controllers() {
+  if (!existsSync(records)) return [];
+  return readdirSync(records).filter(name => name.endsWith('.json')).map(name => json(join(records, name))).filter(record => record.kind === 'controller');
+}
+export async function updateServices({ latest = latestVersion, download = installRelease } = {}) {
+  userOnly();
+  return withServiceOperation('update', () => performUpdate(latest, download));
+}
+async function performUpdate(latest, download) {
+  const held = [], stopped = [];
+  const preferencesPath = join(STATE_HOME, 'updates.json'), selectionPath = join(STATE_HOME, 'service-release.json');
+  const previousPreferences = existsSync(preferencesPath) ? json(preferencesPath) : { enabled: true, lastCheckedAt: 0 };
+  const previous = existsSync(selectionPath) ? json(selectionPath) : {};
+  let activated = false, releaseMaintenance = true;
+  const priorVersions = new Map();
+  try {
+    const managed = controllers();
+    for (const record of managed) owned(record);
+    const live = managed.filter(active);
+    const installed = managed.map(record => record.version || VERSION).reduce((minimum, version) => newer(minimum, version) ? version : minimum, VERSION);
+    const current = previous.version || installed;
+    const version = [await latest(), VERSION, current].reduce((selected, candidate) => newer(candidate, selected) ? candidate : selected);
+    const runningVersions = await Promise.all(live.map(async record => {
+      const value = (await api(record.state, '/api/v1/status')).runtime_version;
+      priorVersions.set(record.id, value); return value;
+    }));
+    if (runningVersions.some(value => !/^\d+\.\d+\.\d+$/.test(value || ''))) throw new Error('Cannot verify the runtime version of a managed controller');
+    if (!newer(version, current) && runningVersions.every(value => !newer(version, value))) { console.log(`software-defence-factory ${current} is up to date.`); return; }
+    const unowned = busyInstallations().filter(state => !live.some(record => record.state === state));
+    if (unowned.length) throw new Error('Unmanaged controllers or executor fences block the update: ' + unowned.join(', '));
+    // Reserve idle controllers before downloads. All mutating API actions are
+    // refused until restart or explicit release, eliminating submit/stop races.
+    for (const record of live) { await api(record.state, '/api/v1/maintenance', { enabled: true }); held.push(record); }
+    download(version);
+    for (const record of live) { stop(record); stopped.push(record); }
+    if (busyInstallations().length) throw new Error('An installation or executor still blocks activation');
+    // Ordinary CLI downloads must never change what an existing service starts.
+    // Only this reserved update transaction may advance the managed selection.
+    activated = true;
+    save(selectionPath, { version });
+    save(preferencesPath, { ...previousPreferences, version, lastCheckedAt: Date.now() });
+    for (const record of stopped) { start(record); await waitHealthy(record, version); }
+    console.log(`Updated to ${version}; restarted ${stopped.length} previously active services. Jobs and history preserved.`);
+  } catch (error) {
+    releaseMaintenance = false;
+    try {
+      if (activated) {
+        for (const record of stopped) stop(record);
+        save(selectionPath, previous);
+        save(preferencesPath, previousPreferences);
+      }
+      for (const record of stopped) { start(record); await waitHealthy(record, priorVersions.get(record.id)); }
+      releaseMaintenance = true;
+    } catch (recoveryError) {
+      throw new Error(`Update failed: ${error.message}. Recovery unconfirmed: ${recoveryError.message}. Maintenance reservations were retained.`);
+    }
+    throw error;
+  } finally {
+    const failures = [];
+    if (releaseMaintenance) for (const record of held) try { await api(record.state, '/api/v1/maintenance', { enabled: false }); } catch (error) { failures.push(`${record.id}: ${error.message}`); }
+    if (failures.length) throw new Error('Maintenance release unconfirmed: ' + failures.join('; '));
+  }
+}
+function automaticUpdates(mode) {
+  if (process.platform !== 'linux') throw new Error('Scheduled service updates currently require Linux/systemd');
+  if (!['on', 'off', 'status'].includes(mode)) throw new Error('Use service updates --auto on|off|status');
+  const timer = join(userUnits, `${updater}.timer`), service = join(userUnits, `${updater}.service`), record = join(records, 'updates.json');
+  if (mode === 'status') { console.log(JSON.stringify({ installed: existsSync(record), ...(existsSync(record) ? { timer: systemctl('show', `${updater}.timer`, '-p', 'ActiveState', '-p', 'NextElapseUSecRealtime') } : {}) })); return; }
+  if (mode === 'off') {
+    if (existsSync(record)) {
+      if (systemctl('show', `${updater}.service`, '-p', 'ActiveState', '--value') === 'activating') throw new Error('An update is running; wait for it to finish before disabling the timer');
+      const data = json(record);
+      for (const [file, hash] of [[timer, data.timerHash], [service, data.serviceHash]]) if (!existsSync(file) || digest(readFileSync(file, 'utf8')) !== hash) throw new Error('Update service was edited; reconcile it before removal');
+      systemctl('disable', '--now', `${updater}.timer`);
+      systemctl('stop', `${updater}.service`);
+      rmSync(timer); rmSync(service); rmSync(record); systemctl('daemon-reload');
+    }
+    console.log('Scheduled updates disabled.'); return;
+  }
+  if (existsSync(record)) { console.log('Scheduled updates are already installed.'); return; }
+  if (existsSync(timer) || existsSync(service)) throw new Error('Refusing to overwrite an unregistered update unit');
+  const serviceText = systemdUnit({ description: 'Software & Defence Factory idle update', argv: [process.execPath, launcher(), 'service', 'update'], directory: homedir(), environment: environment(), oneshot: true });
+  const timerText = `[Unit]\nDescription=Check Factory updates daily when idle\n\n[Timer]\nOnCalendar=daily\nRandomizedDelaySec=1h\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n`;
+  mkdirSync(userUnits, { recursive: true, mode: 0o700 });
+  writeFileSync(service, serviceText, { mode: 0o600 }); writeFileSync(timer, timerText, { mode: 0o600 });
+  save(record, { serviceHash: digest(serviceText), timerHash: digest(timerText) });
+  systemctl('daemon-reload'); systemctl('enable', '--now', `${updater}.timer`); console.log('Daily idle service updates enabled. Busy/unknown installations defer the update.');
+}

package/factory/supervisor.mjs

@@ -1,8 +1,10 @@
 import { writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { configAt, stopContainers } from './lib.mjs';
 import { createController } from './server.mjs';
-const state = process.argv[2], config = configAt(state), lock = join(state, 'supervisor.json');
+export async function supervise(state) {
+const config = configAt(state), lock = join(state, 'supervisor.json');
 writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
 let controller, stopping = false;
 async function shutdown(code = 0) {
@@ -18,3 +20,5 @@ try {
   controller.server.on('error', error => { console.error(error.message); shutdown(1); });
   controller.server.listen(config.port, '127.0.0.1', () => console.log(`Factory controller ready on 127.0.0.1:${config.port}`));
 } catch (error) { console.error(error.message); await shutdown(1); }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await supervise(process.argv[2]);

package/factory/updates.mjs

@@ -104,7 +104,7 @@ export async function bootstrap(args) {
   const busy = busyInstallations();
   const cachedVersion = installedEntry(DATA_HOME, preferences.version) ? preferences.version : VERSION;
   let selectedVersion = newer(cachedVersion, VERSION) ? cachedVersion : VERSION;
-  const automatic = !['stop', 'cancel', 'status', 'serve', 'version', '--version', '-v'].includes(command)
+  const automatic = !['stop', 'cancel', 'status', 'serve', 'service', 'tunnel', 'help', '--help', '-h', 'version', '--version', '-v'].includes(command)
     && preferences.enabled && process.env.SDF_AUTO_UPDATE !== '0'
     && Date.now() - preferences.lastCheckedAt >= DAY && busy.length === 0;
   if (explicit || automatic) {

package/kit/installation.md

@@ -10,6 +10,7 @@
 | Control surface | Existing issue/check/PR workflow unless otherwise selected |
 | Harness, version, model/provider and billing | Unselected |
 | Execution environment and necessary tools | Files, Git, shell and tests; browser for UI; other tools as needed |
+| Worker boot and operator login | Disk unlock, SSH/network/Docker/model startup, selected services, timer and observed reboot evidence; not applicable for method-only use |
 | Start, stop, routing owner and recovery | Manual until automation is qualified; one owner per job |
 | Authority and allowed network/credential references | Identify permissions without key values |
 | Time, concurrency, attempts and actual provider stop limits | Unknown until exercised |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-defence-factory",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Scoped software delivery and defence investigations with isolated jobs, evidence and review",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,9 @@
     "scripts/export-kit.mjs",
     "scripts/probe-platform.mjs",
     "docs/npm.md",
+    "docs/setup.md",
+    "docs/services.md",
+    "docs/recovery.md",
     "docs/quickstart.md",
     "docs/defence-integration.md",
     "docs/ownership.md",

package/scripts/probe-platform.mjs

@@ -68,7 +68,7 @@ try {
   assert(!existsSync(join(state,'jobs',changed.id,'accepted.json')));record('changed candidate cannot inherit earlier approval');
 
   const policy=await work('Synthetic policy change guard');await waitState(policy.id,'awaiting_approval');
-  setConfig({check:'true'});await cli('approve',policy.id);await waitState(policy.id,'failed');
+  setConfig({check:original.check==='true'?':':'true'});await cli('approve',policy.id);await waitState(policy.id,'failed');
   assert(!existsSync(join(state,'jobs',policy.id,'accepted.json')));setConfig({});record('changed check policy cannot inherit earlier approval');
 
   setConfig({check:'exit 17'});