software-defence-factory 0.3.5 → 0.4.0

package/README.md

@@ -23,6 +23,7 @@ Choose the part you need:
 | 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 +69,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

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/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,155 @@
+# Persistent controllers and remote dashboards
+
+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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-defence-factory",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Scoped software delivery and defence investigations with isolated jobs, evidence and review",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,8 @@
     "scripts/export-kit.mjs",
     "scripts/probe-platform.mjs",
     "docs/npm.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'});