import type {

AppLogBackgroundProcess,

AppLogBackgroundProcessRequest,

AppLogProcessMarker,

AppLogProcessMarkerReadOutcome,

AppLogProcessOwnership,

AppLogProcessCommand,

} from '@agent-device/contracts/app-log-runtime';

import type {

HostCommandRequest,

HostCommandResult,

} from '@agent-device/contracts/platform-runtime-host';

import { decodeAppLogProcessMarker } from '@agent-device/capture-kit';

import type { DeviceIdentity } from '@agent-device/kernel/device';

import type { EnvMap } from '@agent-device/kernel/source-value';

import fs from 'node:fs';

import path from 'node:path';

import type { Readable } from 'node:stream';

import { openVerifiedFileForRead } from '@agent-device/host-kit/file';

import { runCmdBackground } from '@agent-device/host-kit/command';

import {

isProcessAlive,

readProcessIdentityFacts,

stopProcessAndConfirmExit,

} from '@agent-device/host-kit/process';

import { requireManagedSessionArtifactPath } from '@agent-device/daemon-contracts/session-artifact-paths';

const APP_LOG_PID_FILENAME = 'app-log.pid';

const APP_LOG_STOP_BUDGET = { termTimeoutMs: 2_000, killTimeoutMs: 2_000 } as const;

type ManagedAppLogCommandChild = Readonly<{

pid?: number;

exitCode?: number | null;

stdout?: Readable | null;

stderr?: Readable | null;

kill(signal?: NodeJS.Signals | number): boolean;

}>;

export type ManagedAppLogCommand = Readonly<{

child: ManagedAppLogCommandChild;

wait: Promise<HostCommandResult>;

}>;

export type ManagedAppLogCommandLauncher = (

command: AppLogProcessCommand,

signal?: AbortSignal,

) => ManagedAppLogCommand | Promise<ManagedAppLogCommand>;

export function createManagedAppLogProcesses(

sessionsDir: string,

env: EnvMap,

options: Readonly<{ launch?: ManagedAppLogCommandLauncher }> = {},

) {

const root = path.resolve(sessionsDir);

const launch =

options.launch ?? ((command, signal) => launchLocalAppLogCommand(command, env, signal));

return Object.freeze({

start: async (request: AppLogBackgroundProcessRequest, signal?: AbortSignal) =>

await startAppLogProcess(root, request, launch, signal),

readMarker: async (markerPath: string) => readMarker(root, markerPath),

clearMarker: async (markerPath: string) => clearMarker(root, markerPath),

inspect: async (marker: AppLogProcessMarker) => await inspectOwnedProcess(marker),

terminate: async (marker: AppLogProcessMarker) => await terminateOwnedProcess(marker),

});

}

export type LegacyAppLogMarkerRecovery = Readonly<{

recovered: readonly string[];

retained: readonly Readonly<{

markerPath: string;

reason: 'invalid' | 'ownership-lost';

message?: string;

device?: DeviceIdentity;

}>[];

}>;

/** Recovers marker-only sessions after the daemon lock is held. */

export async function recoverLegacyAppLogMarkersAfterDaemonLock(

sessionsDir: string,

): Promise<LegacyAppLogMarkerRecovery> {

const recovered: string[] = [];

const retained: Array<{

markerPath: string;

reason: 'invalid' | 'ownership-lost';

message?: string;

device?: DeviceIdentity;

}> = [];

if (!fs.existsSync(sessionsDir)) return { recovered, retained };

const root = path.resolve(sessionsDir);

for (const entry of fs.readdirSync(root, { withFileTypes: true })) {

if (!entry.isDirectory()) continue;

const sessionDir = path.join(root, entry.name);

if (fs.existsSync(path.join(sessionDir, 'app-log.resource.json'))) continue;

const markerPath = path.join(sessionDir, APP_LOG_PID_FILENAME);

const read = readMarker(root, markerPath);

if (read.status === 'missing') continue;

if (read.status === 'invalid') {

retained.push({ markerPath, reason: 'invalid', message: read.message });

continue;

}

const outcome = await terminateOwnedProcess(read.marker);

if (outcome === 'ownership-lost') {

const device = legacyMarkerDeviceIdentity(read.marker.command);

retained.push({ markerPath, reason: 'ownership-lost', ...(device ? { device } : {}) });

continue;

}

clearMarker(root, markerPath);

recovered.push(markerPath);

}

return Object.freeze({ recovered: Object.freeze(recovered), retained: Object.freeze(retained) });

}

function legacyMarkerDeviceIdentity(command: string): DeviceIdentity | undefined {

const android = /(?:^|\s)(?:\S*\/)?adb\s+-s\s+([^\s]+)/.exec(command)?.[1];

if (android) {

return Object.freeze({

id: android,

family: 'android',

kind: android.startsWith('emulator-') ? 'emulator' : 'device',

target: 'mobile',

});

}

const simulator = /(?:^|\s)xcrun\s+(?:--set\s+\S+\s+)?simctl\s+spawn\s+([^\s]+)/.exec(

command,

)?.[1];

if (simulator) {

return Object.freeze({

id: simulator,

family: 'apple',

appleOs: 'ios',

kind: 'simulator',

target: 'mobile',

});

}

const device = /(?:^|\s)xcrun\s+devicectl\b[^\n]*?\s--device\s+([^\s]+)/.exec(command)?.[1];

if (!device) return undefined;

return Object.freeze({

id: device,

family: 'apple',

appleOs: 'ios',

kind: 'device',

target: 'mobile',

iosPhysicalDeviceBackend: 'coredevice',

});

}

async function startAppLogProcess(

root: string,

request: AppLogBackgroundProcessRequest,

launch: ManagedAppLogCommandLauncher,

signal?: AbortSignal,

): Promise<AppLogBackgroundProcess> {

assertMarkerAvailable(root, request.markerPath);

signal?.throwIfAborted();

const background = await launch(request.command, signal);

const child = background.child;

const waitForWrites = forwardProcessOutput(child, request.output);

const marker = await publishProcessMarkerOrRollback(root, request.markerPath, background);

const wait = background.wait

.then(async (result) => {

await waitForWrites();

return result;

})

.finally(() => {

if (request.markerPath && marker) clearPublishedMarker(root, request.markerPath, marker);

});

const terminate = createManagedProcessTermination(child, wait);

return { marker, wait, terminate, [Symbol.asyncDispose]: terminate };

}

function launchLocalAppLogCommand(

command: AppLogProcessCommand,

env: EnvMap,

signal?: AbortSignal,

): ManagedAppLogCommand {

const request = localHostCommand(command);

return runCmdBackground(request.executable, [...request.args], {

allowFailure: request.allowFailure,

cwd: request.cwd,

env: { ...env, ...request.env },

captureOutput: false,

signal,

});

}

function localHostCommand(command: AppLogProcessCommand): HostCommandRequest {

if (command.kind === 'host') return command.request;

return {

executable: 'adb',

args: ['-s', command.serial, ...command.args],

...command.options,

};

}

function assertMarkerAvailable(root: string, markerPath?: string): void {

if (!markerPath) return;

if (readMarker(root, markerPath).status === 'missing') return;

throw new Error('Existing app-log process marker evidence must be recovered before start');

}

function forwardProcessOutput(

child: ManagedAppLogCommandChild,

output: AppLogBackgroundProcessRequest['output'],

): () => Promise<void> {

let writes = Promise.resolve();

let firstWriteError: unknown;

const forward = (chunk: string | Buffer) => {

writes = writes

.then(async () => await output.write(chunk))

.catch((error: unknown) => {

firstWriteError ??= error;

if (typeof child.exitCode !== 'number') child.kill('SIGKILL');

});

};

child.stdout?.on('data', forward);

child.stderr?.on('data', forward);

return async () => {

await writes;

if (firstWriteError !== undefined) throw firstWriteError;

};

}

async function publishProcessMarkerOrRollback(

root: string,

markerPath: string | undefined,

background: ManagedAppLogCommand,

): Promise<AppLogProcessMarker | undefined> {

const marker = background.child.pid

? await resolveProcessMarker(background.child.pid)

: undefined;

try {

if (!marker) {

throw new Error('Managed app-log process did not expose a complete ownership marker');

}

if (markerPath) writeMarker(root, markerPath, marker);

return marker;

} catch (error) {

background.child.kill('SIGKILL');

await background.wait.catch(() => undefined);

throw error;

}

}

function createManagedProcessTermination(

child: ManagedAppLogCommandChild,

wait: AppLogBackgroundProcess['wait'],

): () => Promise<void> {

let termination: Promise<void> | undefined;

return async () =>

await (termination ??= (async () => {

if (typeof child.exitCode !== 'number') {

child.kill('SIGINT');

if (!(await settlesWithin(wait, 2_000))) child.kill('SIGKILL');

}

// A process outside the child's tree, such as one launched inside a simulator, can keep the

// output pipes open after the child exits. Releasing them lets the wait settle on that exit.

if (!(await settlesWithin(wait, 2_000))) {

child.stdout?.destroy();

child.stderr?.destroy();

}

await wait.catch(() => undefined);

})());

}

async function settlesWithin(promise: Promise<unknown>, timeoutMs: number): Promise<boolean> {

return await new Promise((resolve) => {

const timeout = setTimeout(() => resolve(false), timeoutMs);

const settled = () => {

clearTimeout(timeout);

resolve(true);

};

void promise.then(settled, settled);

});

}

function clearPublishedMarker(

root: string,

markerPath: string,

published: AppLogProcessMarker,

): void {

const current = readMarker(root, markerPath);

if (

current.status === 'decoded' &&

current.marker.pid === published.pid &&

current.marker.startTime === published.startTime &&

current.marker.command === published.command

) {

clearMarker(root, markerPath);

}

}

async function processMarker(pid: number): Promise<AppLogProcessMarker | undefined> {

const { startTime, command } = await readProcessIdentityFacts(pid);

if (!startTime || !command) return undefined;

return Object.freeze({

pid,

startTime,

command,

});

}

async function resolveProcessMarker(pid: number): Promise<AppLogProcessMarker | undefined> {

for (let attempt = 0; attempt < 5; attempt += 1) {

const marker = await processMarker(pid);

if (marker) return marker;

await new Promise((resolve) => setTimeout(resolve, 10));

}

return undefined;

}

function readMarker(root: string, markerPath: string): AppLogProcessMarkerReadOutcome {

const resolved = requireManagedMarkerPath(root, markerPath);

let handle: number;

try {

const opened = openVerifiedFileForRead(resolved);

if (opened === undefined) return { status: 'missing' };

handle = opened;

} catch (error) {

return {

status: 'invalid',

message: error instanceof Error ? error.message : 'App-log process marker is invalid',

};

}

try {

const value = JSON.parse(fs.readFileSync(handle, 'utf8')) as unknown;

return decodeAppLogProcessMarker(value);

} catch (error) {

return {

status: 'invalid',

message: error instanceof Error ? error.message : 'App-log process marker is invalid',

};

} finally {

fs.closeSync(handle);

}

}

function writeMarker(root: string, markerPath: string, marker: AppLogProcessMarker): void {

const resolved = requireManagedMarkerPath(root, markerPath);

if (readMarker(root, resolved).status !== 'missing') {

throw new Error(

'Existing app-log process marker evidence must be recovered before replacement',

);

}

fs.mkdirSync(path.dirname(resolved), { recursive: true });

const temporary = `${resolved}.${process.pid}.${Date.now()}.tmp`;

let handle: number | undefined;

let linked = false;

let published = false;

try {

handle = fs.openSync(temporary, 'wx', 0o600);

fs.writeFileSync(handle, `${JSON.stringify(marker)}\n`);

fs.fsyncSync(handle);

fs.closeSync(handle);

handle = undefined;

fs.linkSync(temporary, resolved);

linked = true;

fs.unlinkSync(temporary);

const directory = fs.openSync(path.dirname(resolved), 'r');

try {

fs.fsyncSync(directory);

} finally {

fs.closeSync(directory);

}

published = true;

} finally {

if (handle !== undefined) {

try {

fs.closeSync(handle);

} catch {

// Preserve the publication failure.

}

}

if (!published) {

for (const unresolvedPath of linked ? [resolved, temporary] : [temporary]) {

try {

fs.unlinkSync(unresolvedPath);

} catch {

// Keep the original publication failure.

}

}

}

}

}

function clearMarker(root: string, markerPath: string): void {

const resolved = requireManagedMarkerPath(root, markerPath);

try {

fs.unlinkSync(resolved);

} catch (error) {

if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;

}

}

function requireManagedMarkerPath(root: string, markerPath: string): string {

return requireManagedSessionArtifactPath({

sessionsDir: root,

pathname: markerPath,

basename: APP_LOG_PID_FILENAME,

label: 'App-log process marker',

});

}

async function inspectOwnedProcess(marker: AppLogProcessMarker): Promise<AppLogProcessOwnership> {

if (!isProcessAlive(marker.pid)) return 'missing';

const facts = await readProcessIdentityFacts(marker.pid);

if (facts.zombie) return 'missing';

const matches =

marker.startTime.length > 0 &&

marker.command.length > 0 &&

facts.startTime === marker.startTime &&

facts.command === marker.command;

return matches ? 'owned-alive' : 'ownership-lost';

}

/**

* Stops the marked process through the shared TERM-then-KILL escalation, which re-proves the

* marker's identity before each signal. A marker the host does not confirm is never signaled.

*/

async function terminateOwnedProcess(

marker: AppLogProcessMarker,

): Promise<'terminated' | 'already-missing' | 'ownership-lost'> {

const ownership = await inspectOwnedProcess(marker);

if (ownership === 'missing') return 'already-missing';

if (ownership === 'ownership-lost') return 'ownership-lost';

const stop = await stopProcessAndConfirmExit(

{

pid: marker.pid,

identity: { startTime: marker.startTime, matches: (command) => command === marker.command },

},

APP_LOG_STOP_BUDGET,

);

if (stop.status === 'stopped') return stop.signal ? 'terminated' : 'already-missing';

return 'ownership-lost';

}