feat(control-plane): daemon-core lifecycle-write restart actuator — the R3 seam (#14760) (#14792)

* feat(control-plane): daemon-core lifecycle-write restart actuator — the R3 seam (#14760)

Graduation leaf of Discussion #14501 (the 3rd control-plane leaf) and #14477 Leaf-2 — now unblocked by the
merged ADR-0026 amendment (#14758). Creates the net-new ai/daemons/orchestrator/control-plane/ dir: the
folder-domain IS the R3 boundary (control-plane/ = lifecycle-write divide diagnostics/ = read-observe).

restartRuntimeTarget({runtimeAccess, serviceKey, reason}) delegates the restart THROUGH the ADR-0026
lifecycle-write envelope (DeploymentRuntimeAccessService.applyLifecycle) — never a direct restart, so the
envelope's allowlisted-service-key + anti-thrash + operation-gate guarantees are inherited, not re-derived.
runtimeAccess is injected (the Orchestrator holds the L0 instance), keeping the module a pure testable
delegation. Fail-safe: an unwired runtimeAccess or a missing serviceKey is REFUSED, never a fabricated success.

4 specs green: envelope delegation, both refusals, and a structural R3 firewall (scans src/ai/fleet + the
AgentOS pane + the container healthcheck, asserts NONE import the actuator — physically off-client). Distinct
from the client-reachable FM restartAgent (out of scope).

Scope: the endpoint + its off-client firewall. The live wiring (an orchestrator control-plane caller invoking
this with its DeploymentRuntimeAccessService instance) is the integration point.

Co-Authored-By: Ada (Claude Opus 4.8) <ada@neomjs.dev>

* fix(agentos): control-plane restart actuator honors lifecycle-envelope refusal (#14760)

restartRuntimeTarget wrapped applyLifecycle's outcome as {ok:true}
unconditionally. The lifecycle-write envelope signals a refusal (disabled /
unsupported mechanism / disallowed op / non-allowlisted service key) by
THROWING, so a raw throw leaked to the caller; and an explicit {ok:false}
envelope result would have been masked as success. Now the endpoint catches the
throw and normalizes an {ok:false} result, returning a clean {ok:false, error}
so a false success is impossible on any refusal shape. Two focused specs cover
the throw-refusal and the explicit-{ok:false}-refusal paths (6/6 green).

Addresses @neo-gpt's review on #14792.

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>
Co-authored-by: Ada (Claude Opus 4.8) <ada@neomjs.dev>

Author: 3 people

ai/daemons/orchestrator/control-plane/restartActuator.mjs

@@ -0,0 +1,57 @@
+/**
+ * @module ai/daemons/orchestrator/control-plane/restartActuator
+ * @summary The daemon-core lifecycle-write restart-actuator endpoint (ticket-ref-ok: #14760 owning-leaf anchor, #14477 parent-epic).
+ *
+ * The lifecycle-write half of the R3 boundary. Its **placement is its authority**: living under `control-plane/`
+ * (lifecycle-write) rather than `diagnostics/` (read-observe) IS the structural R3 seam — one folder per
+ * envelope. It is **physically absent from every client Bridge / readiness surface** (not on
+ * `FLEET_WIRE_METHODS`, not on the `registryBridge`, not on a healthcheck): no client RPC may hold or imply a
+ * restart. Only an orchestrator-internal control-plane caller reaches it, and the actual restart is executed
+ * **through** the `lifecycle-write` envelope (`DeploymentRuntimeAccessService.applyLifecycle`) — this endpoint
+ * never restarts a target directly, so the envelope's allowlisted-service-key + anti-thrash + operation-gate
+ * guarantees are inherited, not re-derived.
+ *
+ * Distinct from the existing Fleet Manager `restartAgent` (client-reachable via `createFleetRegistryBridge`),
+ * which is an already-shipped operator-UI lifecycle control and out of scope here.
+ *
+ * `runtimeAccess` is injected (the Orchestrator holds the `DeploymentRuntimeAccessService` instance) rather than
+ * hard-imported — the module stays a pure, testable delegation with no ambient singleton reach.
+ */
+
+/**
+ * @summary Control-plane restart of a known runtime target, routed through the lifecycle-write
+ * envelope. Fail-safe: an absent or misconfigured `runtimeAccess`, or a missing `serviceKey`, is **refused** —
+ * never a fabricated success and never a direct restart that would bypass the envelope's guards.
+ * @param {Object} options
+ * @param {Object} options.runtimeAccess The injected `DeploymentRuntimeAccessService` instance (the L0 holder).
+ * @param {String} options.serviceKey The allowlisted runtime service key to restart (validated by the envelope).
+ * @param {String} [options.reason='control-plane restart'] Audit reason forwarded to the envelope.
+ * @returns {Promise<Object>} `{ok:true, result}` on a delegated restart; `{ok:false, error}` on a refusal.
+ */
+export async function restartRuntimeTarget({runtimeAccess, serviceKey, reason = 'control-plane restart'} = {}) {
+    if (!runtimeAccess || typeof runtimeAccess.applyLifecycle !== 'function') {
+        return {ok: false, error: 'control-plane: no lifecycle-write runtime access wired — refusing restart'};
+    }
+
+    if (typeof serviceKey !== 'string' || serviceKey.length === 0) {
+        return {ok: false, error: 'control-plane: a known service key is required — refusing restart'};
+    }
+
+    // Delegate to the lifecycle-write envelope: it enforces the allowlisted service key, the closed
+    // action set, and the persisted anti-thrash cap. This endpoint adds the R3 placement boundary, not a
+    // second restart path. The envelope signals a refusal by THROWING (disabled / unsupported mechanism /
+    // disallowed op / unknown-or-non-allowlisted service key); catch it so the control-plane endpoint
+    // returns a clean {ok:false} instead of leaking a raw throw, and defensively treat an explicit
+    // {ok:false} envelope result as a refusal too — a false {ok:true} must be impossible on any refusal shape.
+    try {
+        const result = await runtimeAccess.applyLifecycle({serviceKey, operation: 'restart', reason});
+
+        if (result && typeof result === 'object' && result.ok === false) {
+            return {ok: false, error: result.error ?? 'control-plane: lifecycle-write envelope refused the restart', result};
+        }
+
+        return {ok: true, result};
+    } catch (error) {
+        return {ok: false, error: `control-plane: lifecycle-write envelope refused the restart — ${error.message}`};
+    }
+}

test/playwright/unit/ai/daemons/orchestrator/control-plane/restartActuator.spec.mjs

@@ -0,0 +1,80 @@
+import {test, expect}                        from '@playwright/test';
+import {readdirSync, readFileSync, statSync} from 'node:fs';
+import {fileURLToPath}                       from 'node:url';
+
+import {restartRuntimeTarget} from '../../../../../../../ai/daemons/orchestrator/control-plane/restartActuator.mjs';
+
+/** Recursively collect `.mjs` files under a dir (absolute), excluding specs. */
+function collectMjs(absDir) {
+    const out = [];
+    let entries;
+    try { entries = readdirSync(absDir); } catch (error) { return out; }
+    for (const entry of entries) {
+        const abs = `${absDir}/${entry}`;
+        if (statSync(abs).isDirectory()) out.push(...collectMjs(abs));
+        else if (entry.endsWith('.mjs') && !entry.endsWith('.spec.mjs')) out.push(abs);
+    }
+    return out;
+}
+
+test.describe('control-plane/restartActuator — the R3 lifecycle-write restart endpoint', () => {
+    test('delegates the restart through the lifecycle-write envelope (applyLifecycle), never a direct restart', async () => {
+        const calls         = [],
+              runtimeAccess = {applyLifecycle: async args => { calls.push(args); return {serviceKey: args.serviceKey, state: 'restarting'}; }},
+              outcome       = await restartRuntimeTarget({runtimeAccess, serviceKey: 'memory-core', reason: 'stale-source'});
+
+        expect(calls).toEqual([{serviceKey: 'memory-core', operation: 'restart', reason: 'stale-source'}]);
+        expect(outcome).toEqual({ok: true, result: {serviceKey: 'memory-core', state: 'restarting'}});
+    });
+
+    test('propagates a lifecycle-envelope refusal (a throw) as {ok:false} — never a false success', async () => {
+        // The envelope signals a refusal (disabled / disallowed op / non-allowlisted key / anti-thrash)
+        // by throwing; the endpoint must return a clean {ok:false}, not leak the throw or claim success.
+        const runtimeAccess = {applyLifecycle: async () => { throw new Error('runtime-access-disabled'); }},
+              outcome       = await restartRuntimeTarget({runtimeAccess, serviceKey: 'memory-core'});
+
+        expect(outcome.ok).toBe(false);
+        expect(outcome.error).toEqual(expect.stringContaining('envelope refused'));
+        expect(outcome.error).toEqual(expect.stringContaining('runtime-access-disabled'));
+    });
+
+    test('normalizes an explicit {ok:false} envelope result as a refusal — never wrapped as {ok:true}', async () => {
+        const runtimeAccess = {applyLifecycle: async () => ({ok: false, error: 'anti-thrash: too soon since last restart'})},
+              outcome       = await restartRuntimeTarget({runtimeAccess, serviceKey: 'memory-core'});
+
+        expect(outcome.ok).toBe(false);
+        expect(outcome.error).toEqual(expect.stringContaining('anti-thrash'));
+    });
+
+    test('REFUSES when no lifecycle-write runtime access is wired — never a fabricated success', async () => {
+        expect(await restartRuntimeTarget({serviceKey: 'memory-core'})).toEqual({ok: false, error: expect.stringContaining('no lifecycle-write runtime access')});
+        expect(await restartRuntimeTarget({runtimeAccess: {}, serviceKey: 'memory-core'})).toEqual({ok: false, error: expect.stringContaining('no lifecycle-write runtime access')});
+    });
+
+    test('REFUSES a missing service key — never a direct or unbounded restart', async () => {
+        const runtimeAccess = {applyLifecycle: async () => { throw new Error('should not be reached'); }};
+        expect(await restartRuntimeTarget({runtimeAccess})).toEqual({ok: false, error: expect.stringContaining('known service key')});
+        expect(await restartRuntimeTarget({runtimeAccess, serviceKey: ''})).toEqual({ok: false, error: expect.stringContaining('known service key')});
+    });
+
+    test('R3 FIREWALL: no client Bridge / readiness surface imports the restart actuator (physically off-client)', () => {
+        const root = fileURLToPath(new URL('../../../../../../../', import.meta.url)),
+              // The client-reachable surfaces: the app↔fleet wire, the AgentOS pane, and the container healthcheck.
+              client = [
+                  ...collectMjs(`${root}src/ai/fleet`),
+                  ...collectMjs(`${root}apps/agentos/view/fleet`),
+                  `${root}ai/scripts/diagnostics/mcpHealthcheck.mjs`
+              ];
+
+        const importers = client.filter(file => {
+            let src;
+            try { src = readFileSync(file, 'utf8'); } catch (error) { return false; }
+            return /restartActuator/.test(src);
+        });
+
+        // The lifecycle-write restart endpoint must be reachable only from an orchestrator-internal control-plane
+        // caller — never a client RPC / readiness surface (the R3 seam). If this fails, a restart leaked onto
+        // the client boundary.
+        expect(importers, `client surfaces importing the restart actuator: ${importers.join(', ')}`).toEqual([]);
+    });
+});