@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/control/controlExpiryLifecycle.js

@@ -0,0 +1,102 @@
+class DefaultControlExpiryLifecycle {
+    intervalMs;
+    confirmationStore;
+    questionQueue;
+    runtime;
+    persist;
+    emitControlEvent;
+    createQuestionChildResolutionAdapter;
+    timer = null;
+    closed = false;
+    constructor(options) {
+        this.intervalMs = options.intervalMs;
+        this.confirmationStore = options.confirmationStore;
+        this.questionQueue = options.questionQueue;
+        this.runtime = options.runtime;
+        this.persist = options.persist;
+        this.emitControlEvent = options.emitControlEvent;
+        this.createQuestionChildResolutionAdapter = options.createQuestionChildResolutionAdapter;
+    }
+    start() {
+        if (this.closed || this.timer) {
+            return;
+        }
+        this.scheduleNext();
+    }
+    close() {
+        this.closed = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    async expireConfirmations() {
+        const expired = this.confirmationStore.expire();
+        if (expired.length === 0) {
+            return;
+        }
+        await this.persist.confirmations();
+        for (const entry of expired) {
+            await this.emitControlEvent({
+                event: 'confirmation_resolved',
+                actor: 'runner',
+                payload: {
+                    request_id: entry.request.request_id,
+                    nonce_id: entry.nonce_id,
+                    outcome: 'expired'
+                }
+            });
+        }
+    }
+    async expireQuestions(questionChildResolutionAdapter = this.createQuestionChildResolutionAdapter()) {
+        const expired = this.questionQueue.expire();
+        if (expired.length === 0) {
+            return;
+        }
+        await this.persist.questions();
+        for (const record of expired) {
+            await this.emitControlEvent({
+                event: 'question_closed',
+                actor: 'runner',
+                payload: {
+                    question_id: record.question_id,
+                    parent_run_id: record.parent_run_id,
+                    outcome: 'expired',
+                    closed_at: record.closed_at ?? null,
+                    expires_at: record.expires_at ?? null
+                }
+            });
+            await questionChildResolutionAdapter.resolveChildQuestion(record, 'expired');
+        }
+        this.runtime.publish({ source: 'questions.expire' });
+    }
+    scheduleNext() {
+        this.timer = setTimeout(() => {
+            void this.runScheduledSweep();
+        }, this.intervalMs);
+    }
+    async runScheduledSweep() {
+        this.timer = null;
+        if (this.closed) {
+            return;
+        }
+        try {
+            await this.expireConfirmations();
+        }
+        catch {
+            // Preserve prior best-effort background expiry behavior.
+        }
+        try {
+            await this.expireQuestions();
+        }
+        catch {
+            // Preserve prior best-effort background expiry behavior.
+        }
+        if (!this.closed) {
+            this.scheduleNext();
+        }
+    }
+}
+export function createControlExpiryLifecycle(options) {
+    return new DefaultControlExpiryLifecycle(options);
+}

package/dist/orchestrator/src/cli/control/controlHostOwnership.js

@@ -0,0 +1,480 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { writeJsonAtomic } from '../utils/fs.js';
+import { isoTimestamp } from '../utils/time.js';
+import { CONTROL_HOST_DUPLICATE_OWNER_FILE, CONTROL_HOST_OWNER_FILE, CONTROL_HOST_OWNER_LOCK_DIR, CONTROL_HOST_STALE_OWNER_FILE } from './controlPersistenceFiles.js';
+export class DuplicateControlHostOwnerError extends Error {
+    code = 'duplicate_control_host_owner';
+    reason;
+    existingOwner;
+    attemptedOwner;
+    diagnosticPath;
+    constructor(input) {
+        super(formatDuplicateControlHostOwnerMessage(input.reason, input.existingOwner, input.attemptedOwner, input.diagnosticPath));
+        this.name = 'DuplicateControlHostOwnerError';
+        this.reason = input.reason;
+        this.existingOwner = input.existingOwner;
+        this.attemptedOwner = input.attemptedOwner;
+        this.diagnosticPath = input.diagnosticPath;
+    }
+}
+export async function acquireControlHostOwnership(options) {
+    const paths = resolveControlHostOwnershipPaths(options.paths.runDir);
+    const now = options.now ?? isoTimestamp;
+    const isProcessAlive = options.isProcessAlive ?? isLocalProcessAlive;
+    const attemptedOwner = buildControlHostOwnerMetadata(options, paths, now());
+    await mkdir(paths.runDir, { recursive: true });
+    await removePriorOwnershipDiagnostics(paths).catch(() => undefined);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            await mkdir(paths.lockDir);
+            try {
+                await writeJsonAtomic(paths.lockOwnerPath, attemptedOwner);
+                await writeJsonAtomic(paths.ownerPath, attemptedOwner);
+            }
+            catch (error) {
+                await rm(paths.lockDir, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
+            return createControlHostOwnershipHandle(attemptedOwner, paths, now);
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error)) {
+                throw error;
+            }
+            const existingOwner = await readControlHostOwnerMetadataFromPath(paths.lockOwnerPath);
+            const existingState = classifyExistingOwner(existingOwner, {
+                host: attemptedOwner.hostname,
+                isProcessAlive
+            });
+            if (existingState.kind === 'stale') {
+                await reclaimStaleControlHostOwner({
+                    paths,
+                    attemptedOwner,
+                    staleOwner: existingState.owner,
+                    observedAt: now,
+                    isProcessAlive
+                });
+                continue;
+            }
+            const reason = existingState.kind === 'active'
+                ? 'duplicate_control_host_owner'
+                : 'ambiguous_control_host_owner';
+            await writeControlHostOwnershipDiagnostic({
+                paths,
+                reason,
+                action: reason === 'duplicate_control_host_owner'
+                    ? 'duplicate_rejected'
+                    : 'ambiguous_rejected',
+                existingOwner: existingState.owner,
+                attemptedOwner,
+                observedAt: now(),
+                diagnosticPath: paths.duplicateDiagnosticPath
+            });
+            throw new DuplicateControlHostOwnerError({
+                reason,
+                existingOwner: existingState.owner,
+                attemptedOwner,
+                diagnosticPath: paths.duplicateDiagnosticPath
+            });
+        }
+    }
+    throw new DuplicateControlHostOwnerError({
+        reason: 'ambiguous_control_host_owner',
+        existingOwner: await readControlHostOwnerMetadataFromPath(paths.lockOwnerPath),
+        attemptedOwner,
+        diagnosticPath: paths.duplicateDiagnosticPath
+    });
+}
+export async function readControlHostOwnerMetadata(runDir) {
+    return await readControlHostOwnerMetadataFromPath(join(runDir, CONTROL_HOST_OWNER_FILE));
+}
+export function buildControlHostOwnershipPollingPayload(metadata) {
+    return {
+        status: 'owned',
+        reason: null,
+        updated_at: metadata.updated_at,
+        owner: summarizeControlHostOwner(metadata),
+        diagnostic_path: null,
+        lock_dir: metadata.lock_dir,
+        owner_path: metadata.owner_path
+    };
+}
+export async function readControlHostOwnershipDiagnosticSummary(runDir) {
+    const duplicate = await readControlHostOwnershipDiagnosticFromPath(join(runDir, CONTROL_HOST_DUPLICATE_OWNER_FILE));
+    if (duplicate) {
+        return buildControlHostOwnershipPollingPayloadFromDiagnostic(duplicate);
+    }
+    const stale = await readControlHostOwnershipDiagnosticFromPath(join(runDir, CONTROL_HOST_STALE_OWNER_FILE));
+    if (stale) {
+        return buildControlHostOwnershipPollingPayloadFromDiagnostic(stale);
+    }
+    return null;
+}
+export async function readControlHostOwnershipOperatorHint(runDir) {
+    const diagnostic = await readControlHostOwnershipDiagnosticSummary(runDir);
+    if (!diagnostic || diagnostic.status === 'owned') {
+        return null;
+    }
+    const owner = diagnostic.owner;
+    const attempted = diagnostic.attempted_owner ?? null;
+    const ownerText = owner
+        ? `owner pid=${owner.pid} host=${owner.hostname} task=${owner.task_id ?? 'unknown'} run=${owner.run_id} pipeline=${owner.pipeline_id ?? 'unknown'}`
+        : 'owner metadata unavailable';
+    const attemptedText = attempted
+        ? `attempted pid=${attempted.pid} host=${attempted.hostname}`
+        : 'attempted owner unavailable';
+    return `control-host ownership diagnostic: ${diagnostic.reason ?? diagnostic.status}; ${ownerText}; ${attemptedText}; artifact=${diagnostic.diagnostic_path ?? 'unknown'}`;
+}
+export function normalizeControlHostOwnershipPollingPayload(value) {
+    if (!isRecordLike(value)) {
+        return null;
+    }
+    const status = normalizePollingStatus(value.status);
+    if (!status) {
+        return null;
+    }
+    return {
+        status,
+        reason: normalizeDiagnosticReason(value.reason),
+        updated_at: typeof value.updated_at === 'string' ? value.updated_at : '',
+        owner: normalizeControlHostOwnerSummary(value.owner),
+        attempted_owner: normalizeControlHostOwnerSummary(value.attempted_owner),
+        diagnostic_path: typeof value.diagnostic_path === 'string' ? value.diagnostic_path : null,
+        lock_dir: typeof value.lock_dir === 'string' ? value.lock_dir : null,
+        owner_path: typeof value.owner_path === 'string' ? value.owner_path : null
+    };
+}
+function createControlHostOwnershipHandle(metadata, paths, now) {
+    return {
+        metadata,
+        polling: buildControlHostOwnershipPollingPayload(metadata),
+        async release() {
+            const currentOwner = await readControlHostOwnerMetadataFromPath(paths.lockOwnerPath);
+            if (!currentOwner || currentOwner.owner_token !== metadata.owner_token) {
+                return;
+            }
+            const releasedAt = now();
+            const releasedOwner = {
+                ...metadata,
+                status: 'released',
+                updated_at: releasedAt,
+                released_at: releasedAt
+            };
+            await writeJsonAtomic(paths.ownerPath, releasedOwner);
+            await rm(paths.lockDir, { recursive: true, force: true });
+        }
+    };
+}
+function buildControlHostOwnerMetadata(options, paths, timestamp) {
+    return {
+        schema_version: 1,
+        status: 'owned',
+        owner_token: randomUUID(),
+        acquired_at: timestamp,
+        updated_at: timestamp,
+        released_at: null,
+        repo_root: normalizeNullableString(options.repoRoot),
+        task_id: normalizeNullableString(options.taskId),
+        run_id: options.runId,
+        run_dir: paths.runDir,
+        pipeline_id: normalizeNullableString(options.pipelineId),
+        pid: options.processId ?? process.pid,
+        ppid: options.parentProcessId === undefined ? process.ppid : options.parentProcessId,
+        hostname: options.host ?? hostname(),
+        cwd: options.cwd === undefined ? process.cwd() : options.cwd,
+        argv: options.argv ?? process.argv.slice(),
+        lock_dir: paths.lockDir,
+        lock_owner_path: paths.lockOwnerPath,
+        owner_path: paths.ownerPath
+    };
+}
+function resolveControlHostOwnershipPaths(runDir) {
+    return {
+        runDir,
+        lockDir: join(runDir, CONTROL_HOST_OWNER_LOCK_DIR),
+        reclaimLockDir: join(runDir, `${CONTROL_HOST_OWNER_LOCK_DIR}.reclaim`),
+        lockOwnerPath: join(runDir, CONTROL_HOST_OWNER_LOCK_DIR, 'owner.json'),
+        ownerPath: join(runDir, CONTROL_HOST_OWNER_FILE),
+        duplicateDiagnosticPath: join(runDir, CONTROL_HOST_DUPLICATE_OWNER_FILE),
+        staleDiagnosticPath: join(runDir, CONTROL_HOST_STALE_OWNER_FILE)
+    };
+}
+async function reclaimStaleControlHostOwner(input) {
+    try {
+        await mkdir(input.paths.reclaimLockDir);
+    }
+    catch (error) {
+        if (isAlreadyExistsError(error)) {
+            return false;
+        }
+        throw error;
+    }
+    try {
+        const currentOwner = await readControlHostOwnerMetadataFromPath(input.paths.lockOwnerPath);
+        if (!currentOwner || currentOwner.owner_token !== input.staleOwner.owner_token) {
+            return false;
+        }
+        const currentState = classifyExistingOwner(currentOwner, {
+            host: input.attemptedOwner.hostname,
+            isProcessAlive: input.isProcessAlive
+        });
+        if (currentState.kind !== 'stale') {
+            return false;
+        }
+        await writeControlHostOwnershipDiagnostic({
+            paths: input.paths,
+            reason: 'stale_control_host_owner',
+            action: 'stale_reclaimed',
+            existingOwner: currentOwner,
+            attemptedOwner: input.attemptedOwner,
+            observedAt: input.observedAt(),
+            diagnosticPath: input.paths.staleDiagnosticPath
+        });
+        await rm(input.paths.lockDir, { recursive: true, force: true });
+        return true;
+    }
+    finally {
+        await rm(input.paths.reclaimLockDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function writeControlHostOwnershipDiagnostic(input) {
+    const diagnostic = {
+        schema_version: 1,
+        reason: input.reason,
+        observed_at: input.observedAt,
+        run_dir: input.paths.runDir,
+        lock_dir: input.paths.lockDir,
+        diagnostic_path: input.diagnosticPath,
+        existing_owner: input.existingOwner,
+        attempted_owner: input.attemptedOwner,
+        action: input.action
+    };
+    await writeJsonAtomic(input.diagnosticPath, diagnostic);
+    return diagnostic;
+}
+async function removePriorOwnershipDiagnostics(paths) {
+    await Promise.all([
+        rm(paths.duplicateDiagnosticPath, { force: true }),
+        rm(paths.staleDiagnosticPath, { force: true })
+    ]);
+}
+function classifyExistingOwner(owner, input) {
+    if (!owner) {
+        return { kind: 'ambiguous', owner: null };
+    }
+    if (!Number.isInteger(owner.pid) || owner.pid <= 0) {
+        return { kind: 'ambiguous', owner };
+    }
+    if (owner.hostname && owner.hostname !== input.host) {
+        return { kind: 'active', owner };
+    }
+    return input.isProcessAlive(owner.pid)
+        ? { kind: 'active', owner }
+        : { kind: 'stale', owner };
+}
+function isLocalProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code !== 'ESRCH';
+    }
+}
+async function readControlHostOwnerMetadataFromPath(path) {
+    try {
+        return normalizeControlHostOwnerMetadata(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+async function readControlHostOwnershipDiagnosticFromPath(path) {
+    try {
+        return normalizeControlHostOwnershipDiagnostic(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeControlHostOwnerMetadata(value) {
+    if (!isRecordLike(value)) {
+        return null;
+    }
+    if (value.schema_version !== 1 || (value.status !== 'owned' && value.status !== 'released')) {
+        return null;
+    }
+    if (typeof value.owner_token !== 'string' ||
+        typeof value.acquired_at !== 'string' ||
+        typeof value.updated_at !== 'string' ||
+        typeof value.run_id !== 'string' ||
+        typeof value.run_dir !== 'string' ||
+        typeof value.pid !== 'number' ||
+        typeof value.hostname !== 'string' ||
+        typeof value.lock_dir !== 'string' ||
+        typeof value.lock_owner_path !== 'string' ||
+        typeof value.owner_path !== 'string') {
+        return null;
+    }
+    return {
+        schema_version: 1,
+        status: value.status,
+        owner_token: value.owner_token,
+        acquired_at: value.acquired_at,
+        updated_at: value.updated_at,
+        released_at: typeof value.released_at === 'string' ? value.released_at : null,
+        repo_root: typeof value.repo_root === 'string' ? value.repo_root : null,
+        task_id: typeof value.task_id === 'string' ? value.task_id : null,
+        run_id: value.run_id,
+        run_dir: value.run_dir,
+        pipeline_id: typeof value.pipeline_id === 'string' ? value.pipeline_id : null,
+        pid: value.pid,
+        ppid: typeof value.ppid === 'number' ? value.ppid : null,
+        hostname: value.hostname,
+        cwd: typeof value.cwd === 'string' ? value.cwd : null,
+        argv: Array.isArray(value.argv)
+            ? value.argv.filter((entry) => typeof entry === 'string')
+            : [],
+        lock_dir: value.lock_dir,
+        lock_owner_path: value.lock_owner_path,
+        owner_path: value.owner_path
+    };
+}
+function normalizeControlHostOwnershipDiagnostic(value) {
+    if (!isRecordLike(value) || value.schema_version !== 1) {
+        return null;
+    }
+    const reason = normalizeDiagnosticReason(value.reason);
+    if (!reason) {
+        return null;
+    }
+    const attemptedOwner = normalizeControlHostOwnerMetadata(value.attempted_owner);
+    if (!attemptedOwner) {
+        return null;
+    }
+    const action = value.action === 'duplicate_rejected' ||
+        value.action === 'ambiguous_rejected' ||
+        value.action === 'stale_reclaimed'
+        ? value.action
+        : reason === 'stale_control_host_owner'
+            ? 'stale_reclaimed'
+            : reason === 'duplicate_control_host_owner'
+                ? 'duplicate_rejected'
+                : 'ambiguous_rejected';
+    return {
+        schema_version: 1,
+        reason,
+        observed_at: typeof value.observed_at === 'string' ? value.observed_at : '',
+        run_dir: typeof value.run_dir === 'string' ? value.run_dir : attemptedOwner.run_dir,
+        lock_dir: typeof value.lock_dir === 'string' ? value.lock_dir : attemptedOwner.lock_dir,
+        diagnostic_path: typeof value.diagnostic_path === 'string' ? value.diagnostic_path : '',
+        existing_owner: normalizeControlHostOwnerMetadata(value.existing_owner),
+        attempted_owner: attemptedOwner,
+        action
+    };
+}
+function buildControlHostOwnershipPollingPayloadFromDiagnostic(diagnostic) {
+    const status = diagnostic.action === 'stale_reclaimed'
+        ? 'stale_reclaimed'
+        : diagnostic.action === 'ambiguous_rejected'
+            ? 'ambiguous_rejected'
+            : 'duplicate_rejected';
+    return {
+        status,
+        reason: diagnostic.reason,
+        updated_at: diagnostic.observed_at,
+        owner: diagnostic.existing_owner ? summarizeControlHostOwner(diagnostic.existing_owner) : null,
+        attempted_owner: summarizeControlHostOwner(diagnostic.attempted_owner),
+        diagnostic_path: diagnostic.diagnostic_path,
+        lock_dir: diagnostic.lock_dir,
+        owner_path: diagnostic.existing_owner?.owner_path ?? diagnostic.attempted_owner.owner_path
+    };
+}
+function summarizeControlHostOwner(metadata) {
+    return {
+        owner_token: metadata.owner_token,
+        status: metadata.status,
+        pid: metadata.pid,
+        ppid: metadata.ppid,
+        hostname: metadata.hostname,
+        acquired_at: metadata.acquired_at,
+        updated_at: metadata.updated_at,
+        released_at: metadata.released_at,
+        repo_root: metadata.repo_root,
+        task_id: metadata.task_id,
+        run_id: metadata.run_id,
+        run_dir: metadata.run_dir,
+        pipeline_id: metadata.pipeline_id,
+        lock_dir: metadata.lock_dir,
+        owner_path: metadata.owner_path
+    };
+}
+function normalizeControlHostOwnerSummary(value) {
+    if (!isRecordLike(value)) {
+        return null;
+    }
+    if (typeof value.owner_token !== 'string' ||
+        typeof value.status !== 'string' ||
+        typeof value.pid !== 'number' ||
+        typeof value.hostname !== 'string' ||
+        typeof value.acquired_at !== 'string' ||
+        typeof value.updated_at !== 'string' ||
+        typeof value.run_id !== 'string' ||
+        typeof value.run_dir !== 'string' ||
+        typeof value.lock_dir !== 'string' ||
+        typeof value.owner_path !== 'string') {
+        return null;
+    }
+    const status = value.status === 'released' ? 'released' : 'owned';
+    return {
+        owner_token: value.owner_token,
+        status,
+        pid: value.pid,
+        ppid: typeof value.ppid === 'number' ? value.ppid : null,
+        hostname: value.hostname,
+        acquired_at: value.acquired_at,
+        updated_at: value.updated_at,
+        released_at: typeof value.released_at === 'string' ? value.released_at : null,
+        repo_root: typeof value.repo_root === 'string' ? value.repo_root : null,
+        task_id: typeof value.task_id === 'string' ? value.task_id : null,
+        run_id: value.run_id,
+        run_dir: value.run_dir,
+        pipeline_id: typeof value.pipeline_id === 'string' ? value.pipeline_id : null,
+        lock_dir: value.lock_dir,
+        owner_path: value.owner_path
+    };
+}
+function normalizeDiagnosticReason(value) {
+    return value === 'duplicate_control_host_owner' ||
+        value === 'ambiguous_control_host_owner' ||
+        value === 'stale_control_host_owner'
+        ? value
+        : null;
+}
+function normalizePollingStatus(value) {
+    return value === 'owned' ||
+        value === 'duplicate_rejected' ||
+        value === 'ambiguous_rejected' ||
+        value === 'stale_reclaimed'
+        ? value
+        : null;
+}
+function normalizeNullableString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isAlreadyExistsError(error) {
+    return error?.code === 'EEXIST';
+}
+function formatDuplicateControlHostOwnerMessage(reason, existingOwner, attemptedOwner, diagnosticPath) {
+    const ownerText = existingOwner
+        ? `existing pid=${existingOwner.pid} host=${existingOwner.hostname} task=${existingOwner.task_id ?? 'unknown'} run=${existingOwner.run_id} pipeline=${existingOwner.pipeline_id ?? 'unknown'}`
+        : 'existing owner metadata unavailable';
+    return `control-host ownership rejected (${reason}): ${ownerText}; attempted pid=${attemptedOwner.pid} host=${attemptedOwner.hostname}; diagnostic=${diagnosticPath}`;
+}