@xenon-device-management/xenon 2.6.0 → 2.6.1

package/lib/src/services/recording/RecordingOrchestrator.js

@@ -135,9 +135,22 @@ class RecordingError extends Error {
     }
 }
 exports.RecordingError = RecordingError;
+/**
+ * The live preview's leave path, as a page that stops watching uses it: after
+ * a short grace, the phone's preview is stopped and its hold released unless
+ * someone watches it or another recording reads it. Imported when called:
+ * control.ts is a router, loaded long after this service.
+ */
+function leaveDevice(udid) {
+    void Promise.resolve().then(() => __importStar(require('../../app/routers/control'))).then(({ previewLeaves }) => previewLeaves.leave(udid))
+        .catch((err) => {
+        var _a;
+        recLog.warn(`Could not hand ${udid} to the preview's leave path: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+    });
+}
 let RecordingOrchestrator = class RecordingOrchestrator {
     constructor(deps = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         /**
          * Recording ids currently being closed out. Both the user-initiated stop and
          * an ffmpeg self-exit finalize rows, and they can land at the same instant —
@@ -158,7 +171,8 @@ let RecordingOrchestrator = class RecordingOrchestrator {
         this.ensureMjpegPortFn = (_h = deps.ensureMjpegPortFn) !== null && _h !== void 0 ? _h : ensureMjpegForRecording_1.ensureMjpegForRecording;
         this.nodeSourceFn = (_j = deps.nodeSourceFn) !== null && _j !== void 0 ? _j : ((udid, actorId) => (0, nodeRecordingSource_1.recordingSourceFor)(udid, actorId));
         this.probeDurationMsFn = (_k = deps.probeDurationMsFn) !== null && _k !== void 0 ? _k : probeDuration_1.probeVideoDurationMs;
-        this.now = (_l = deps.now) !== null && _l !== void 0 ? _l : Date.now;
+        this.leaveDeviceFn = (_l = deps.leaveDeviceFn) !== null && _l !== void 0 ? _l : leaveDevice;
+        this.now = (_m = deps.now) !== null && _m !== void 0 ? _m : Date.now;
     }
     get busyPrecheck() {
         return this._deps.busyPrecheck;
@@ -398,6 +412,7 @@ let RecordingOrchestrator = class RecordingOrchestrator {
                 failReason = (_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : 'ffmpeg_stop_failed';
             }
             // Its ffmpeg is done reading; a group's composite stops before this.
+            const fromNode = this.nodeSources.has(r.id);
             yield this.closeNodeSource(r.id);
             // How long the video actually is, not how long the session was open. Those
             // agree only while capture keeps up: a recording whose device died at 26s
@@ -444,7 +459,7 @@ let RecordingOrchestrator = class RecordingOrchestrator {
                 recLog.warn(`finalize failed for ${r.id}: ${err === null || err === void 0 ? void 0 : err.message}`);
             }
             this.gate.release(r.id);
-            yield this.releaseLockIfNotInheritedFromMosaic(r.device_udid, (_c = r.device_host) !== null && _c !== void 0 ? _c : '127.0.0.1');
+            yield this.letGoOfDevice(r.device_udid, (_c = r.device_host) !== null && _c !== void 0 ? _c : '127.0.0.1', fromNode);
             if (durationMs !== undefined) {
                 durationHistogram.record(durationMs, {
                     outcome: status === 'STOPPED' ? attributes_1.OUTCOME.SUCCESS : attributes_1.OUTCOME.FAILURE,
@@ -647,57 +662,27 @@ let RecordingOrchestrator = class RecordingOrchestrator {
         }))();
     }
     /**
-     * Stop-time unblock that respects the mosaic preview. If the mosaic's
-     * stream service is still actively streaming this device (its lock value
-     * is `manual_${udid}` — same string the orchestrator wrote, but conceptually
-     * owned by the mosaic), we leave the lock in place so the preview keeps
-     * working and so automation doesn't grab the device underneath it.
+     * Let go of a phone whose recording has ended.
+     *
+     * This server's own phone goes to the live preview's leave path, as a page
+     * that stops watching it does. After a short grace, which also lets this
+     * recording's own ffmpeg connection drop, its preview is stopped and its
+     * hold released, unless someone watches it or another recording reads it.
+     * Whether its stream is running says nothing: the recording starts the
+     * stream itself when none runs (ensureMjpegForRecording). Taking that
+     * stream for a preview's kept the phone held, with nobody watching, until
+     * the stream's idle watchdog ten minutes later.
+     *
+     * A node's phone has no stream on this server, so nobody here watches it:
+     * its hold goes at once.
      */
-    releaseLockIfNotInheritedFromMosaic(udid, host) {
+    letGoOfDevice(udid, host, fromNode) {
         return __awaiter(this, void 0, void 0, function* () {
-            let mosaicStreamRunning = false;
-            try {
-                // Lazy import — keeps the orchestrator usable in tests that don't
-                // wire stream services into the DI container.
-                const { default: IOSStreamService } = yield Promise.resolve().then(() => __importStar(require('../../device-managers/ios/IOSStreamService')));
-                const ios = typedi_1.Container.get(IOSStreamService);
-                const iosSession = ios.getStreamStatus(udid);
-                if ((iosSession === null || iosSession === void 0 ? void 0 : iosSession.status) === 'running')
-                    mosaicStreamRunning = true;
-            }
-            catch (_a) {
-                /* ignore — service may not be registered in this context */
-            }
-            if (!mosaicStreamRunning) {
-                try {
-                    const { default: AndroidStreamService } = yield Promise.resolve().then(() => __importStar(require('../../device-managers/android/AndroidStreamService')));
-                    const android = typedi_1.Container.get(AndroidStreamService);
-                    const aSession = android.getStreamStatus(udid);
-                    if ((aSession === null || aSession === void 0 ? void 0 : aSession.status) === 'running')
-                        mosaicStreamRunning = true;
-                }
-                catch (_b) {
-                    /* ignore */
-                }
-            }
-            // H.264 preview (androidH264) has no MJPEG session — check it too or we
-            // drop the mosaic lock underneath a live WebCodecs tile.
-            if (!mosaicStreamRunning) {
-                try {
-                    const { default: AndroidH264StreamService } = yield Promise.resolve().then(() => __importStar(require('../../device-managers/android/AndroidH264StreamService')));
-                    if (typedi_1.Container.get(AndroidH264StreamService).getMultiplexer(udid)) {
-                        mosaicStreamRunning = true;
-                    }
-                }
-                catch (_c) {
-                    /* ignore */
-                }
-            }
-            if (mosaicStreamRunning) {
-                recLog.info(`Recording stop: keeping manual lock on ${udid} because the mosaic preview is still active.`);
+            if (fromNode) {
+                yield this.tryUnblock(udid, host);
                 return;
             }
-            yield this.tryUnblock(udid, host);
+            this.leaveDeviceFn(udid);
         });
     }
     addBookmark(groupId, recordingId, timecodeMs, label, note) {

package/lib/test/integration/cross-workflow.spec.js

@@ -51,6 +51,7 @@ const sinon_1 = __importDefault(require("sinon"));
 const RecordingOrchestrator_1 = require("../../src/services/recording/RecordingOrchestrator");
 const concurrency_gate_1 = require("../../src/services/recording/concurrency-gate");
 const deviceStoreModule = __importStar(require("../../src/data-service/device-store"));
+const artifact_store_1 = require("../helpers/artifact-store");
 /**
  * The six scenarios from the spec's cross-workflow risk matrix
  * (docs/superpowers/specs/2026-04-27-multi-device-mosaic-and-proof-pack-design.md
@@ -58,7 +59,7 @@ const deviceStoreModule = __importStar(require("../../src/data-service/device-st
  * workflow is broken by the new free-form recording surface.
  */
 function makeOrch(overrides = {}) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     const busyPrecheck = (_a = overrides.busyPrecheck) !== null && _a !== void 0 ? _a : { findBusy: sinon_1.default.stub().resolves([]) };
     const store = (_b = overrides.store) !== null && _b !== void 0 ? _b : {
         create: sinon_1.default.stub().callsFake((i) => __awaiter(this, void 0, void 0, function* () { return (Object.assign({ id: `rec-${i.deviceUdid}` }, i)); })),
@@ -73,7 +74,14 @@ function makeOrch(overrides = {}) {
     };
     const blockDeviceFn = (_e = overrides.blockDeviceFn) !== null && _e !== void 0 ? _e : sinon_1.default.stub().resolves();
     const unblockDeviceFn = (_f = overrides.unblockDeviceFn) !== null && _f !== void 0 ? _f : sinon_1.default.stub().resolves();
-    const eventMgr = (_g = overrides.eventMgr) !== null && _g !== void 0 ? _g : {
+    // Each phone is this server's own, read from a live MJPEG port: the real
+    // ones would look the phone up and start its stream.
+    const nodeSourceFn = (_g = overrides.nodeSourceFn) !== null && _g !== void 0 ? _g : sinon_1.default.stub().resolves(null);
+    const ensureMjpegPortFn = (_h = overrides.ensureMjpegPortFn) !== null && _h !== void 0 ? _h : sinon_1.default.stub().resolves(9100);
+    // Where a stopped recording hands its phone: the preview's leave path,
+    // which releases the hold once nobody watches it.
+    const leaveDeviceFn = (_j = overrides.leaveDeviceFn) !== null && _j !== void 0 ? _j : sinon_1.default.stub();
+    const eventMgr = (_k = overrides.eventMgr) !== null && _k !== void 0 ? _k : {
         emitRecordingStarted: sinon_1.default.stub(),
         emitRecordingStopped: sinon_1.default.stub(),
         emitRecordingFailed: sinon_1.default.stub(),
@@ -88,10 +96,26 @@ function makeOrch(overrides = {}) {
         blockDeviceFn,
         eventMgr: eventMgr,
         unblockDeviceFn,
+        nodeSourceFn,
+        ensureMjpegPortFn,
+        leaveDeviceFn,
     });
-    return { orch, busyPrecheck, store, gate, videoPipeline, blockDeviceFn, unblockDeviceFn, eventMgr };
+    return {
+        orch,
+        busyPrecheck,
+        store,
+        gate,
+        videoPipeline,
+        blockDeviceFn,
+        unblockDeviceFn,
+        leaveDeviceFn,
+        eventMgr,
+    };
 }
 describe('Cross-workflow integration: manual + automation safety (6 scenarios)', () => {
+    // start() resolves each recording's file through the ArtifactStore, as the
+    // server registers it at boot.
+    (0, artifact_store_1.useArtifactStore)();
     let factoryStub;
     beforeEach(() => {
         factoryStub = sinon_1.default
@@ -150,8 +174,8 @@ describe('Cross-workflow integration: manual + automation safety (6 scenarios)',
         const passedSessionIds = calls.map((c) => c.args[0].sessionId);
         (0, chai_1.expect)(new Set(passedSessionIds).size).to.equal(2);
     }));
-    it('4. ffmpeg stop throws (simulated device unplug) — Recording marked FAILED, manual block released', () => __awaiter(void 0, void 0, void 0, function* () {
-        const { orch, store, unblockDeviceFn, videoPipeline } = makeOrch({
+    it('4. ffmpeg stop throws (simulated device unplug) — Recording marked FAILED, phone handed on to release its block', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { orch, store, leaveDeviceFn } = makeOrch({
             store: {
                 listGroup: sinon_1.default.stub().resolves([
                     {
@@ -172,7 +196,7 @@ describe('Cross-workflow integration: manual + automation safety (6 scenarios)',
         yield orch.stop('grp-X');
         const finalizeArgs = store.finalize.firstCall.args[1];
         (0, chai_1.expect)(finalizeArgs.status).to.equal('FAILED');
-        (0, chai_1.expect)(unblockDeviceFn.calledWith('U1', '127.0.0.1')).to.equal(true);
+        (0, chai_1.expect)(leaveDeviceFn.calledOnceWith('U1')).to.equal(true);
     }));
     it('5. server restart with orphan RECORDING row — recoverOnBoot marks FAILED + releases block', () => __awaiter(void 0, void 0, void 0, function* () {
         const { orch, store, unblockDeviceFn } = makeOrch({

package/lib/test/unit/recording-orchestrator.spec.js

@@ -60,7 +60,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 function makeOrch(overrides = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     const busyPrecheck = (_a = overrides.busyPrecheck) !== null && _a !== void 0 ? _a : { findBusy: sinon_1.default.stub().resolves([]) };
     const store = (_b = overrides.store) !== null && _b !== void 0 ? _b : {
         create: sinon_1.default.stub().callsFake((i) => __awaiter(this, void 0, void 0, function* () { return (Object.assign({ id: `rec-${i.deviceUdid}` }, i)); })),
@@ -82,7 +82,9 @@ function makeOrch(overrides = {}) {
     const ensureMjpegPortFn = (_g = overrides.ensureMjpegPortFn) !== null && _g !== void 0 ? _g : sinon_1.default.stub().callsFake(() => __awaiter(this, void 0, void 0, function* () { return 9100; }));
     // This server's own phones, unless a test says otherwise.
     const nodeSourceFn = (_h = overrides.nodeSourceFn) !== null && _h !== void 0 ? _h : sinon_1.default.stub().resolves(null);
-    const eventMgr = (_j = overrides.eventMgr) !== null && _j !== void 0 ? _j : {
+    // Where a stopped recording hands its phone: the preview's leave path.
+    const leaveDeviceFn = (_j = overrides.leaveDeviceFn) !== null && _j !== void 0 ? _j : sinon_1.default.stub();
+    const eventMgr = (_k = overrides.eventMgr) !== null && _k !== void 0 ? _k : {
         emitRecordingStarted: sinon_1.default.stub(),
         emitRecordingStopped: sinon_1.default.stub(),
         emitRecordingFailed: sinon_1.default.stub(),
@@ -99,6 +101,7 @@ function makeOrch(overrides = {}) {
         unblockDeviceFn,
         ensureMjpegPortFn,
         nodeSourceFn,
+        leaveDeviceFn,
         now: overrides.now,
     });
     return {
@@ -112,6 +115,7 @@ function makeOrch(overrides = {}) {
         eventMgr,
         ensureMjpegPortFn,
         nodeSourceFn,
+        leaveDeviceFn,
     };
 }
 // On a hub, a node's phone is recorded from a loopback relay to its node's
@@ -181,6 +185,17 @@ describe('RecordingOrchestrator: a node’s phone', () => {
         yield orch.stop(groupId);
         (0, chai_1.expect)(relay.close.calledOnce).to.equal(true);
     }));
+    // This server runs no stream of a node's phone, so nobody here can be
+    // watching it: its hold goes as soon as the recording is finalized.
+    it('releases a node phone’s hold at once, not through the leave path', () => __awaiter(void 0, void 0, void 0, function* () {
+        const relay = relayFor('N1', 5555);
+        const store = rowStore();
+        const { orch, unblockDeviceFn, leaveDeviceFn } = makeOrch({ nodeSourceFn: relay.fn, store });
+        const { groupId } = yield orch.start({ udids: ['N1'], actorId: 'alice' });
+        yield orch.stop(groupId);
+        (0, chai_1.expect)(unblockDeviceFn.calledWith('N1', 'h')).to.equal(true);
+        (0, chai_1.expect)(leaveDeviceFn.called).to.equal(false);
+    }));
     it('closes the relay when that phone’s recording can’t start', () => __awaiter(void 0, void 0, void 0, function* () {
         const relay = relayFor('N1', 5555);
         const videoPipeline = {
@@ -371,7 +386,7 @@ describe('RecordingOrchestrator.start', () => {
 describe('RecordingOrchestrator.stop', () => {
     // compositeOutputPath and per-device paths resolve through ArtifactStore.
     (0, artifact_store_1.useArtifactStore)();
-    it('finalizes, releases gate, releases blocks, emits stopped', () => __awaiter(void 0, void 0, void 0, function* () {
+    it('finalizes, releases gate, hands each phone to the leave path, emits stopped', () => __awaiter(void 0, void 0, void 0, function* () {
         const store = {
             listGroup: sinon_1.default.stub().resolves([
                 {
@@ -399,15 +414,63 @@ describe('RecordingOrchestrator.stop', () => {
         };
         const unblockDeviceFn = sinon_1.default.stub().resolves();
         const eventMgr = { emitRecordingStopped: sinon_1.default.stub() };
-        const { orch } = makeOrch({ store, gate, videoPipeline, unblockDeviceFn, eventMgr });
+        const { orch, leaveDeviceFn } = makeOrch({
+            store,
+            gate,
+            videoPipeline,
+            unblockDeviceFn,
+            eventMgr,
+        });
         yield orch.stop('grp-1');
         (0, chai_1.expect)(videoPipeline.stopRecording.callCount).to.equal(2);
         (0, chai_1.expect)(store.finalize.callCount).to.equal(2);
         (0, chai_1.expect)(gate.release.callCount).to.equal(2);
-        (0, chai_1.expect)(unblockDeviceFn.callCount).to.equal(2);
+        // The leave path releases each hold once nobody watches the phone; the
+        // recording doesn't release it itself.
+        (0, chai_1.expect)(leaveDeviceFn.getCalls().map((c) => c.args[0])).to.deep.equal(['U1', 'U2']);
+        (0, chai_1.expect)(unblockDeviceFn.called).to.equal(false);
         (0, chai_1.expect)(eventMgr.emitRecordingStopped.callCount).to.equal(1);
     }));
-    it('marks FAILED when ffmpeg stop throws but still releases the block', () => __awaiter(void 0, void 0, void 0, function* () {
+    // A recording starts its phone's stream when none runs
+    // (ensureMjpegForRecording). Taking that running stream for a preview kept
+    // the phone held until the stream's idle watchdog, ten minutes later.
+    it('hands the phone to the leave path even while its stream runs', () => __awaiter(void 0, void 0, void 0, function* () {
+        const { default: AndroidStreamService } = yield Promise.resolve().then(() => __importStar(require('../../src/device-managers/android/AndroidStreamService')));
+        const had = typedi_1.Container.has(AndroidStreamService);
+        const previous = had ? typedi_1.Container.get(AndroidStreamService) : undefined;
+        typedi_1.Container.set(AndroidStreamService, {
+            getStreamStatus: () => ({ status: 'running', viewerCount: 0 }),
+        });
+        try {
+            const store = {
+                listGroup: sinon_1.default.stub().resolves([
+                    {
+                        id: 'r1',
+                        device_udid: 'U1',
+                        device_host: '127.0.0.1',
+                        file_path: '/nonexistent/r1.mp4',
+                        started_at: new Date(Date.now() - 5000),
+                    },
+                ]),
+                finalize: sinon_1.default.stub().resolves({}),
+            };
+            const videoPipeline = {
+                startRecording: sinon_1.default.stub(),
+                stopRecording: sinon_1.default.stub().resolves('/tmp/x.mp4'),
+                stopComposite: sinon_1.default.stub().resolves(null),
+            };
+            const { orch, leaveDeviceFn } = makeOrch({ store, videoPipeline });
+            yield orch.stop('grp-1');
+            (0, chai_1.expect)(leaveDeviceFn.calledOnceWith('U1')).to.equal(true);
+        }
+        finally {
+            if (had)
+                typedi_1.Container.set(AndroidStreamService, previous);
+            else
+                typedi_1.Container.remove(AndroidStreamService);
+        }
+    }));
+    it('marks FAILED when ffmpeg stop throws but still hands the phone on', () => __awaiter(void 0, void 0, void 0, function* () {
         const store = {
             listGroup: sinon_1.default.stub().resolves([
                 {
@@ -425,11 +488,10 @@ describe('RecordingOrchestrator.stop', () => {
             stopRecording: sinon_1.default.stub().rejects(new Error('ffmpeg died')),
             stopComposite: sinon_1.default.stub().resolves(null),
         };
-        const unblockDeviceFn = sinon_1.default.stub().resolves();
-        const { orch } = makeOrch({ store, videoPipeline, unblockDeviceFn });
+        const { orch, leaveDeviceFn } = makeOrch({ store, videoPipeline });
         yield orch.stop('grp-1');
         (0, chai_1.expect)(store.finalize.firstCall.args[1].status).to.equal('FAILED');
-        (0, chai_1.expect)(unblockDeviceFn.calledWith('U1', '127.0.0.1')).to.equal(true);
+        (0, chai_1.expect)(leaveDeviceFn.calledOnceWith('U1')).to.equal(true);
     }));
 });
 describe('RecordingOrchestrator.recoverOnBoot', () => {

package/lib/test/unit/recording-source-ended.spec.js

@@ -54,6 +54,8 @@ function makeOrch(row, overrides = {}) {
         emitRecordingAnnotation: sinon_1.default.stub(),
     };
     const unblockDeviceFn = sinon_1.default.stub().resolves();
+    // Where an ended recording hands its phone: the preview's leave path.
+    const leaveDeviceFn = sinon_1.default.stub();
     // Never spawn ffmpeg from a unit test; individual cases override this.
     const probeDurationMsFn = (_c = overrides.probeDurationMsFn) !== null && _c !== void 0 ? _c : sinon_1.default.stub().resolves(undefined);
     const orch = new RecordingOrchestrator_1.RecordingOrchestrator({
@@ -66,8 +68,18 @@ function makeOrch(row, overrides = {}) {
         blockDeviceFn: sinon_1.default.stub().resolves(),
         unblockDeviceFn,
         ensureMjpegPortFn: sinon_1.default.stub().resolves(9100),
+        leaveDeviceFn,
     });
-    return { orch, store, gate, videoPipeline, eventMgr, unblockDeviceFn, probeDurationMsFn };
+    return {
+        orch,
+        store,
+        gate,
+        videoPipeline,
+        eventMgr,
+        unblockDeviceFn,
+        leaveDeviceFn,
+        probeDurationMsFn,
+    };
 }
 describe('RecordingOrchestrator: ffmpeg exiting on its own', () => {
     // The in-memory stores, also when this file runs on its own: without
@@ -106,13 +118,14 @@ describe('RecordingOrchestrator: ffmpeg exiting on its own', () => {
         (0, chai_1.expect)(store.finalize.firstCall.args[1].status).to.equal('FAILED');
         (0, chai_1.expect)(store.finalize.firstCall.args[1].failReason).to.equal('empty_or_corrupt_mp4');
     }));
-    it('releases the gate slot and the device lock', () => __awaiter(void 0, void 0, void 0, function* () {
+    it('releases the gate slot and hands the phone on to release its hold', () => __awaiter(void 0, void 0, void 0, function* () {
         const row = makeRow();
-        const { orch, gate, unblockDeviceFn } = makeOrch(row);
+        const { orch, gate, leaveDeviceFn } = makeOrch(row);
         gate.tryAcquire(['rec-1']);
         yield orch.handleSourceEnded('rec-1', 0);
         (0, chai_1.expect)(gate.tryAcquire(['rec-1']), 'slot must be free again').to.be.true;
-        (0, chai_1.expect)(unblockDeviceFn.called, 'manual lock released').to.be.true;
+        (0, chai_1.expect)(leaveDeviceFn.calledOnceWith(row.device_udid), 'phone handed to the leave path').to.be
+            .true;
     }));
     it('does nothing when the row was already finalized', () => __awaiter(void 0, void 0, void 0, function* () {
         // A manual Stop that won the race already closed it out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenon-device-management/xenon",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Xenon - Intelligent Mobile Infrastructure. A self-healing device orchestration platform for Appium.",
   "main": "./lib/src/index.js",
   "exports": {