feat(ai): FleetManager turnkey stopAgent + restartAgent (#13336) (#13337)

Expose the mutating lifecycle verbs on the control-plane facade, completing the
start->stop->restart operator surface (the #13015 MVP criterion). Pure exposure
of the already-merged FleetLifecycleService primitives.

restartAgent routes through the provisioned start path (stop -> startAgent), NOT
lifecycleService.restart -- which re-starts with no cwd and would re-spawn a
provisioned agent in the FM dir, silently forking checkout-path-keyed auto-memory
(the failure the provisioned start path prevents). removeAgent stays out: blocked
on the auto-memory reconciliation policy, and removeAgentRepo forbids auto-wiring.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>

Author: neo-opus-ada

ai/services/fleet/FleetManager.mjs

@@ -139,6 +139,33 @@ class FleetManager extends Base {
             managedRoot: this.getManagedRoot()
         });
     }
+
+    /**
+     * @summary Turnkey stop: gracefully stop an agent's harness process (`SIGTERM`, then `SIGKILL` after
+     * the timeout) via the lifecycle collaborator. A thin delegation — stopping a process needs no
+     * `managedRoot` / provisioning, so it forwards straight to `FleetLifecycleService.stop`, mirroring how
+     * `fleetRepoStatus` forwards to its aggregator.
+     * @param {String} agentId Registry agent id.
+     * @returns {Promise<Object>} `{success, id, state}` from the lifecycle service's `stop`.
+     */
+    stopAgent(agentId) {
+        return this.getLifecycleService().stop(agentId);
+    }
+
+    /**
+     * @summary Turnkey restart: stop the agent, then start it again through the provisioned path
+     * ({@link startAgent}) — so the restarted harness re-ensures its repo and runs inside ITS checkout,
+     * not the Fleet Manager's own directory. Deliberately NOT a delegation to the lifecycle service's own
+     * `restart`, which re-starts with no `cwd`: that would re-spawn a provisioned agent in the wrong
+     * directory, and the checkout-path-keyed auto-memory would silently fork (the exact failure the
+     * provisioned start path prevents). Restarting a non-running agent is just a provisioned start.
+     * @param {String} agentId Registry agent id.
+     * @returns {Promise<Object>} the agent's lifecycle status (see {@link startAgent}).
+     */
+    async restartAgent(agentId) {
+        await this.stopAgent(agentId);
+        return this.startAgent(agentId);
+    }
 }
 
 export default Neo.setupClass(FleetManager);

test/playwright/unit/ai/FleetManager.spec.mjs

@@ -89,6 +89,35 @@ test.describe('Neo.ai.services.fleet.FleetManager', () => {
         expect(result).toEqual([{agentId: 'a'}]);
     });
 
+    test('stopAgent delegates to the lifecycle service stop with the agent id', async () => {
+        const calls     = [],
+              lifecycle = {stop: id => { calls.push(id); return Promise.resolve({success: true, id, state: 'stopped'}); }};
+
+        FleetManager.lifecycleService = lifecycle;
+
+        const result = await FleetManager.stopAgent('agent-a');
+
+        expect(calls).toEqual(['agent-a']);
+        expect(result).toMatchObject({success: true, id: 'agent-a', state: 'stopped'});
+    });
+
+    test('restartAgent stops then re-starts via the PROVISIONED path (preserving the repo cwd)', async () => {
+        const order     = [],
+              lifecycle = {stop: id => { order.push(`stop:${id}`); return Promise.resolve({success: true, id, state: 'stopped'}); }};
+
+        FleetManager.managedRoot         = '/managed/root';
+        FleetManager.lifecycleService    = lifecycle;
+        FleetManager.provisionAndStartFn = async args => { order.push(`provisionStart:${args.agentId}`); return {state: 'running'}; };
+
+        const status = await FleetManager.restartAgent('agent-a');
+
+        // stop runs BEFORE the provisioned start, and the start goes through the provision-then-start
+        // composer (NOT lifecycleService.restart, which the stub deliberately omits) → the restarted
+        // agent re-runs in its provisioned checkout, not the Fleet Manager's dir.
+        expect(order).toEqual(['stop:agent-a', 'provisionStart:agent-a']);
+        expect(status.state).toBe('running');
+    });
+
     test('seams default to the real composers (a no-injection construction wires them)', () => {
         expect(FleetManager.getProvisionAndStartFn()).toBe(startAgentProvisioned);
         expect(FleetManager.getRepoStatusFn()).toBe(inspectFleetRepos);