@amsterdamdatalabs/enact-operator 0.1.2

package/dist/lanes/team/index.js

@@ -0,0 +1,748 @@
+import { appendFileSync, existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { z } from 'zod';
+import { ensureLayout, layoutPath, readJsonFile, validateJsonFile, writeJson, appendLedger, createReview, listInbox, listReviews, pushInboxItem, resolveInboxItems, updateInboxItems, updateReview, upsertInboxItem, createTask, getTask, listTasks, updateTask, canAutoClose, } from '../../operator/operatorRuntimeCore.js';
+import { clearContinuationState, readContinuationState, refreshContinuationTeamSignals, touchContinuationActivity, } from '../../shared/workflow/continuation/continuation.js';
+import { acknowledgeContinuationFollowUp, buildTeamMessageFollowUpDedupeKey, enqueueContinuationFollowUp, } from '../../shared/workflow/continuation/continuationFollowUp.js';
+import { getRalph } from '../../lanes/ralph/index.js';
+import { getUltrawork } from '../../lanes/ultrawork/index.js';
+import { touchDelegatedSession, registerDelegatedSession } from '../../shared/workflow/delegation/delegatedSession.js';
+const TEAM_SCHEMA_VERSION = 1;
+const OperatorTeamExecutorSchema = z.object({
+    id: z.string(),
+    agentId: z.string(),
+    role: z.string(),
+    status: z.enum(['idle', 'busy', 'offline', 'stale']),
+    assignedTaskIds: z.array(z.string()).optional(),
+    pendingInjectedMessageIds: z.array(z.string()),
+    lastInjectedTurnMarker: z.string().nullable(),
+    leaseExpiresAt: z.string().nullable(),
+    lastHeartbeatAt: z.string().nullable(),
+    lastLifecycleSource: z.string().nullable().optional(),
+    orphanReason: z.string().nullable().optional(),
+    continuationId: z.string().nullable().optional(),
+    runtime: z.object({
+        backend: z.enum(['tmux', 'mock']),
+        sessionName: z.string().nullable(),
+        windowName: z.string().nullable(),
+        command: z.string().nullable(),
+        logFile: z.string(),
+    }),
+}).transform((executor) => ({
+    ...executor,
+    assignedTaskIds: executor.assignedTaskIds ?? executor.assignedTaskIds ?? [],
+}));
+const OperatorTeamMessageSchema = z.object({
+    id: z.string(),
+    subject: z.string(),
+    body: z.string(),
+    kind: z.enum(['inbox', 'review', 'system']),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    createdAt: z.string(),
+});
+const OperatorTeamStateSchema = z.object({
+    schemaVersion: z.literal(TEAM_SCHEMA_VERSION),
+    id: z.string(),
+    name: z.string(),
+    active: z.boolean(),
+    baseBranch: z.string(),
+    backend: z.object({
+        kind: z.enum(['tmux', 'mock']),
+        available: z.boolean(),
+        sessionName: z.string().nullable(),
+        degradedReason: z.string().optional(),
+    }),
+    executors: z.array(OperatorTeamExecutorSchema),
+    taskQueue: z.array(z.string()).optional(),
+    messages: z.array(OperatorTeamMessageSchema),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+}).transform((state) => ({
+    ...state,
+    taskQueue: state.taskQueue ?? state.taskQueue ?? [],
+}));
+function now() {
+    return new Date().toISOString();
+}
+function teamFile(root) {
+    return layoutPath(root, 'team', 'team.json');
+}
+function teamLogFile(root, executorId) {
+    return layoutPath(root, 'team', 'logs', `${executorId}.log`);
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 32);
+}
+function tmuxAvailable() {
+    if (process.env.VITEST) {
+        return false;
+    }
+    try {
+        execFileSync('sh', ['-lc', 'command -v tmux'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ensureTmuxSession(sessionName) {
+    try {
+        execFileSync('tmux', ['has-session', '-t', sessionName], { stdio: 'ignore' });
+    }
+    catch {
+        execFileSync('tmux', ['new-session', '-d', '-s', sessionName, '-n', 'operator'], { stdio: 'ignore' });
+    }
+}
+function createTmuxWindow(sessionName, windowName, command) {
+    try {
+        execFileSync('tmux', ['new-window', '-t', sessionName, '-n', windowName, command], { stdio: 'ignore' });
+    }
+    catch {
+        // best effort — tmux session may already be gone
+    }
+}
+function autopilotActiveOnDisk(root) {
+    const path = layoutPath(root, 'state', 'autopilot.json');
+    if (!existsSync(path)) {
+        return false;
+    }
+    const raw = readJsonFile(path);
+    if (raw === undefined || raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    return Boolean(raw.active);
+}
+function teamLaneOwnsContinuation(root) {
+    return !getRalph(root)?.active && !getUltrawork(root)?.active && !autopilotActiveOnDisk(root);
+}
+function teamContinuationPayload(team) {
+    return {
+        id: team.id,
+        active: team.active,
+        taskQueue: team.taskQueue,
+        executors: team.executors.map((executor) => ({
+            pendingInjectedMessageIds: executor.pendingInjectedMessageIds,
+            assignedTaskIds: executor.assignedTaskIds,
+        })),
+    };
+}
+function reconcileExecutor(executor) {
+    if (executor.leaseExpiresAt && Date.parse(executor.leaseExpiresAt) < Date.now() && executor.status === 'busy') {
+        return { ...executor, status: 'stale' };
+    }
+    return executor;
+}
+function resolveRecipientExecutors(team, recipient) {
+    if (!recipient || recipient === 'all' || recipient === '*') {
+        return team.executors;
+    }
+    return team.executors.filter((executor) => executor.id === recipient
+        || executor.agentId === recipient
+        || executor.role === recipient);
+}
+function normalizeTeamState(state) {
+    if (!state)
+        return null;
+    return {
+        ...state,
+        schemaVersion: TEAM_SCHEMA_VERSION,
+        executors: Array.isArray(state.executors)
+            ? state.executors.map((executor) => {
+                const assignedTaskIds = Array.isArray(executor.assignedTaskIds)
+                    ? executor.assignedTaskIds
+                    : Array.isArray(executor.assignedTaskIds)
+                        ? executor.assignedTaskIds
+                        : [];
+                return {
+                    ...executor,
+                    assignedTaskIds,
+                    pendingInjectedMessageIds: Array.isArray(executor.pendingInjectedMessageIds) ? executor.pendingInjectedMessageIds : [],
+                    lastInjectedTurnMarker: typeof executor.lastInjectedTurnMarker === 'string' ? executor.lastInjectedTurnMarker : null,
+                };
+            })
+            : [],
+        taskQueue: Array.isArray(state.taskQueue)
+            ? state.taskQueue
+            : Array.isArray(state.taskQueue)
+                ? state.taskQueue
+                : [],
+        messages: Array.isArray(state.messages) ? state.messages : [],
+    };
+}
+function migrateTeamState(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Team state must be an object.');
+    }
+    const state = raw;
+    const schemaVersion = typeof state.schemaVersion === 'number' ? state.schemaVersion : 0;
+    if (schemaVersion !== 0 && schemaVersion !== TEAM_SCHEMA_VERSION) {
+        throw new Error(`Unsupported team schemaVersion ${schemaVersion}.`);
+    }
+    return normalizeTeamState({
+        ...state,
+        schemaVersion: TEAM_SCHEMA_VERSION,
+    });
+}
+function load(root) {
+    const path = teamFile(root);
+    const raw = readJsonFile(path);
+    if (raw === undefined) {
+        return null;
+    }
+    return normalizeTeamState(validateJsonFile(path, migrateTeamState(raw), OperatorTeamStateSchema));
+}
+function save(root, state) {
+    const next = normalizeTeamState({ ...state, updatedAt: now() });
+    writeJson(teamFile(root), next);
+    return next;
+}
+export function probeTmux() {
+    return { available: tmuxAvailable() };
+}
+export function createTeam(root, name, executors, baseBranch = 'main', options) {
+    ensureLayout(root);
+    const tmuxReady = tmuxAvailable();
+    const sessionName = `operator-${slug(basename(root))}-${slug(name)}`;
+    if (tmuxReady)
+        ensureTmuxSession(sessionName);
+    const teamId = `team_${randomUUID().slice(0, 10)}`;
+    const state = save(root, {
+        schemaVersion: TEAM_SCHEMA_VERSION,
+        id: teamId,
+        name,
+        active: true,
+        baseBranch,
+        backend: {
+            kind: tmuxReady ? 'tmux' : 'mock',
+            available: tmuxReady,
+            sessionName: tmuxReady ? sessionName : null,
+            ...(tmuxReady ? {} : { degradedReason: 'tmux not installed, using mock runtime' }),
+        },
+        executors: executors.map((executor) => {
+            const ds = registerDelegatedSession(root, {
+                kind: 'team_executor',
+                externalRef: `${teamId}:${executor.id}`,
+                parentLane: 'team',
+                parentLaneId: teamId,
+                reuseActive: false,
+                metadata: { teamId, executorId: executor.id, source: 'operator_team_init' },
+            });
+            return {
+                id: executor.id,
+                role: executor.role,
+                agentId: executor.agentId ?? executor.id,
+                status: 'idle',
+                assignedTaskIds: [],
+                pendingInjectedMessageIds: [],
+                lastInjectedTurnMarker: null,
+                leaseExpiresAt: null,
+                lastHeartbeatAt: null,
+                continuationId: ds.continuationId,
+                runtime: {
+                    backend: tmuxReady ? 'tmux' : 'mock',
+                    sessionName: tmuxReady ? sessionName : null,
+                    windowName: null,
+                    command: null,
+                    logFile: teamLogFile(root, executor.id),
+                },
+            };
+        }),
+        taskQueue: [],
+        messages: [],
+        createdAt: now(),
+        updatedAt: now(),
+    });
+    appendLedger(root, { kind: 'executor', action: 'team_init', detail: `Created team ${name} with ${executors.length} executors` });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Operator team initialized',
+        body: tmuxReady ? `tmux session ${sessionName} ready` : 'tmux missing, using mock runtime',
+        status: 'open',
+    });
+    clearContinuationState(root, 'team initialized', 'operator_team_init');
+    if (options?.initialTaskTitle?.trim()) {
+        queueTeamTask(root, options.initialTaskTitle.trim(), options.initialOwner ?? 'operator');
+        return readTeam(root) ?? state;
+    }
+    return state;
+}
+export function readTeam(root) {
+    const team = load(root);
+    if (!team)
+        return null;
+    return {
+        ...team,
+        executors: team.executors.map(reconcileExecutor),
+    };
+}
+export function resumeTeam(root) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state)
+        return null;
+    if (state.backend.available && state.backend.sessionName)
+        ensureTmuxSession(state.backend.sessionName);
+    appendLedger(root, { kind: 'executor', action: 'team_resume', detail: `Resumed team ${state.name}` });
+    const executors = state.executors.map((ex) => {
+        const e = reconcileExecutor({ ...ex });
+        let orphanReason = e.orphanReason ?? null;
+        if (e.status === 'stale') {
+            orphanReason = orphanReason ?? 'lease-expired-or-missed-heartbeat';
+        }
+        if (state.backend.kind === 'tmux' && !state.backend.available && e.runtime.backend === 'tmux') {
+            orphanReason = orphanReason ?? 'tmux-backend-unavailable';
+        }
+        return {
+            ...e,
+            lastLifecycleSource: 'operator_team_resume',
+            orphanReason,
+        };
+    });
+    const patched = { ...state, active: true, executors };
+    const next = save(root, patched);
+    for (const ex of executors) {
+        if (ex.continuationId) {
+            try {
+                touchDelegatedSession(root, ex.continuationId, { source: 'operator_team_resume' });
+            }
+            catch {
+                // executor row may predate Phase 3 registry
+            }
+        }
+    }
+    const cont = readContinuationState(root);
+    const orphanIds = executors.filter((e) => e.orphanReason).map((e) => e.id).sort();
+    const orphanExecutorContinuations = executors
+        .filter((e) => e.orphanReason && e.continuationId)
+        .map((e) => ({ executorId: e.id, continuationId: e.continuationId }));
+    if (orphanIds.length > 0) {
+        const keyPart = orphanIds.join(',');
+        enqueueContinuationFollowUp(root, {
+            sessionId: cont.lastSessionId,
+            dedupeKey: `followup:team-resume:${state.id}:${keyPart}`,
+            trigger: 'team-resume',
+            lane: 'team',
+            laneId: state.id,
+            prompt: `Team resumed with executor anomaly flags (${keyPart}). Inspect operator_team_status_detailed, reconcile leases or stale executors, and run operator_team_heartbeat or operator_team_spawn as needed.`,
+            metadata: {
+                orphanExecutorIds: orphanIds,
+                orphanExecutorContinuations,
+                source: 'operator_team_resume',
+            },
+        });
+    }
+    if (teamLaneOwnsContinuation(root)) {
+        refreshContinuationTeamSignals(root, teamContinuationPayload(next), listTasks(root), listInbox(root), 'operator_team_resume', 'team resume');
+    }
+    else {
+        touchContinuationActivity(root, 'operator_team_resume');
+    }
+    return next;
+}
+export function shutdownTeam(root) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state)
+        return null;
+    if (state.backend.available && state.backend.sessionName) {
+        try {
+            execFileSync('tmux', ['kill-session', '-t', state.backend.sessionName], { stdio: 'ignore' });
+        }
+        catch {
+            // best effort — tmux session may already be gone
+        }
+    }
+    appendLedger(root, { kind: 'executor', action: 'team_shutdown', detail: `Shut down team ${state.name}` });
+    updateInboxItems(root, (item) => item.status === 'open', 'resolved');
+    const next = save(root, { ...state, active: false });
+    clearContinuationState(root, 'team shutdown', 'operator_team_shutdown');
+    return next;
+}
+export function spawnTeamExecutor(root, executorId, command) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const executor = team.executors.find((entry) => entry.id === executorId);
+    if (!executor)
+        return null;
+    const executorCommand = command ?? `printf 'Operator executor ${executorId} ready\n'; while true; do sleep 3600; done`;
+    if (team.backend.available && team.backend.sessionName) {
+        createTmuxWindow(team.backend.sessionName, executorId, executorCommand);
+        executor.runtime.windowName = executorId;
+    }
+    executor.runtime.command = executorCommand;
+    executor.lastHeartbeatAt = now();
+    appendExecutorLog(root, executorId, `spawn ${executorCommand}`);
+    appendLedger(root, { kind: 'executor', action: 'executor_spawn', detail: `Spawned executor ${executorId}`, executorId });
+    return save(root, team);
+}
+export function appendExecutorLog(root, executorId, line) {
+    ensureLayout(root);
+    appendFileSync(teamLogFile(root, executorId), `${now()} ${line}\n`, 'utf8');
+}
+export function enqueueTeamTask(root, taskId) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team || team.taskQueue.includes(taskId))
+        return team;
+    team.taskQueue.push(taskId);
+    updateTask(root, taskId, { status: 'queued' });
+    appendLedger(root, { kind: 'task', action: 'task_enqueued', detail: `Queued ${taskId}`, taskId });
+    const next = save(root, team);
+    clearContinuationState(root, `team queued ${taskId}`, 'operator_team_queue');
+    return next;
+}
+export function claimTeamTask(root, taskId, executorId) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const executor = team.executors.find((entry) => entry.id === executorId);
+    if (!executor || !team.taskQueue.includes(taskId))
+        return null;
+    executor.status = 'busy';
+    if (!executor.assignedTaskIds.includes(taskId)) {
+        executor.assignedTaskIds.push(taskId);
+    }
+    executor.lastHeartbeatAt = now();
+    executor.leaseExpiresAt = new Date(Date.now() + 20 * 60 * 1000).toISOString();
+    team.taskQueue = team.taskQueue.filter((entry) => entry !== taskId);
+    updateTask(root, taskId, { owner: executorId, status: 'in_progress', claimedAt: now(), reviewStatus: 'none' }, executorId);
+    appendExecutorLog(root, executorId, `claim ${taskId}`);
+    appendLedger(root, { kind: 'task', action: 'task_claim', detail: `Executor ${executorId} claimed ${taskId}`, executorId, taskId });
+    const next = save(root, team);
+    clearContinuationState(root, `team claimed ${taskId}`, 'operator_team_claim');
+    return next;
+}
+export function completeTeamTask(root, taskId, executorId, result) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const executor = team.executors.find((entry) => entry.id === executorId);
+    if (!executor || !executor.assignedTaskIds.includes(taskId))
+        return null;
+    executor.status = 'idle';
+    executor.assignedTaskIds = executor.assignedTaskIds.filter((entry) => entry !== taskId);
+    executor.lastHeartbeatAt = now();
+    executor.leaseExpiresAt = null;
+    appendExecutorLog(root, executorId, `complete ${taskId}: ${result}`);
+    const wiBeforeComplete = getTask(root, taskId);
+    const previousStatus = wiBeforeComplete?.status ?? 'in_progress';
+    updateTask(root, taskId, {
+        status: 'review',
+        result,
+        reviewStatus: 'pending',
+        notes: [...(wiBeforeComplete?.notes ?? []), result],
+    }, executorId);
+    createReview(root, { taskId, reviewer: 'reviewer', summary: result });
+    pushInboxItem(root, {
+        kind: 'review',
+        subject: `Review requested for ${taskId}`,
+        body: result,
+        taskId,
+        from: executorId,
+        to: 'reviewer',
+    });
+    appendLedger(root, { kind: 'task', action: 'task_complete', detail: `Executor ${executorId} completed ${taskId}`, executorId, taskId });
+    const next = save(root, team);
+    clearContinuationState(root, `team completed ${taskId}`, 'operator_team_complete');
+    return next;
+}
+export function recordTeamReview(root, input) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const taskId = input.taskId;
+    if (!taskId) {
+        throw new Error('recordTeamReview: taskId is required');
+    }
+    const existing = listReviews(root).find((review) => review.taskId === taskId && review.status === 'pending');
+    if (existing) {
+        updateReview(root, existing.id, {
+            reviewer: input.reviewer,
+            status: input.status,
+            summary: input.notes,
+            notes: [...existing.notes, input.notes],
+        });
+    }
+    else {
+        createReview(root, {
+            taskId,
+            reviewer: input.reviewer,
+            status: input.status,
+            summary: input.notes,
+            notes: [input.notes],
+        });
+    }
+    if (input.status === 'approved') {
+        const wi = getTask(root, taskId);
+        if (!wi) {
+            throw new Error(`recordTeamReview: Task ${taskId} not found — cannot auto-complete on reviewer approval.`);
+        }
+        if (!canAutoClose(wi)) {
+            // Cross-repo or Epic — defer auto-complete; emit ledger entry.
+            // Stop-policy §I4 and closure-policy coercion already enforce this; this is defense-in-depth.
+            appendLedger(root, {
+                kind: 'task_close_deferred',
+                action: 'team_review_approved_no_autoclose',
+                detail: `Team reviewer approved task "${taskId}" but auto-close is blocked (closureScope=${wi.closureScope ?? 'undefined'}, kind=${wi.kind ?? 'undefined'}). Operator must call operator_task_acknowledge_close to record manual close.`,
+                metadata: { taskId, closureScope: wi.closureScope, kind: wi.kind, reason: 'cross-repo-manual-close' },
+            });
+            updateTask(root, taskId, { reviewStatus: 'approved' }, input.reviewer);
+        }
+        else {
+            updateTask(root, taskId, { status: 'completed', reviewStatus: 'approved', completedAt: now() }, input.reviewer);
+        }
+        resolveInboxItems(root, taskId);
+    }
+    else if (input.status === 'changes_requested') {
+        updateTask(root, taskId, {
+            status: 'blocked',
+            reviewStatus: 'changes_requested',
+            blockers: [...(getTask(root, taskId)?.blockers ?? []), input.notes],
+        }, input.reviewer);
+    }
+    else {
+        updateTask(root, taskId, { status: 'review', reviewStatus: 'pending' }, input.reviewer);
+    }
+    team.messages.push({
+        id: `msg_${randomUUID().slice(0, 10)}`,
+        subject: `Review ${input.status}`,
+        body: input.notes,
+        kind: 'review',
+        from: input.reviewer,
+        createdAt: now(),
+    });
+    appendLedger(root, {
+        kind: 'review',
+        action: `review_${input.status}`,
+        detail: `${input.reviewer} marked ${input.taskId} as ${input.status}`,
+        actor: input.reviewer,
+        taskId: input.taskId,
+    });
+    const next = save(root, team);
+    clearContinuationState(root, `team review ${input.status} for ${input.taskId}`, 'operator_team_review');
+    return next;
+}
+export function pushTeamMessage(root, input) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const message = {
+        id: `msg_${randomUUID().slice(0, 10)}`,
+        createdAt: now(),
+        ...input,
+    };
+    team.messages.push(message);
+    const recipients = resolveRecipientExecutors(team, input.to);
+    for (const executor of recipients) {
+        if (!executor.pendingInjectedMessageIds.includes(message.id)) {
+            executor.pendingInjectedMessageIds.push(message.id);
+        }
+        executor.lastInjectedTurnMarker = message.id;
+    }
+    pushInboxItem(root, {
+        kind: input.kind === 'review' ? 'review' : 'inbox',
+        subject: input.subject,
+        body: input.body,
+        from: input.from,
+        to: input.to,
+    });
+    appendLedger(root, {
+        kind: 'executor',
+        action: 'team_message',
+        detail: `${input.subject}: ${input.body}`,
+        metadata: {
+            messageId: message.id,
+            pendingRecipientIds: recipients.map((executor) => executor.id),
+        },
+    });
+    const next = save(root, team);
+    const cont = readContinuationState(root);
+    const continuationIds = recipients
+        .map((executor) => executor.continuationId)
+        .filter((id) => typeof id === 'string' && id.length > 0);
+    enqueueContinuationFollowUp(root, {
+        sessionId: cont.lastSessionId,
+        dedupeKey: buildTeamMessageFollowUpDedupeKey(team.id, message.id),
+        trigger: 'team-message',
+        lane: 'team',
+        laneId: team.id,
+        prompt: `Pending injected team message "${message.id}" (${input.subject}): acknowledge with operator_team_message_ack once the executor has applied it.`,
+        metadata: {
+            teamMessageId: message.id,
+            teamId: team.id,
+            source: 'operator_team_message',
+            ...(continuationIds.length > 0 ? { continuationIds } : {}),
+        },
+    });
+    if (teamLaneOwnsContinuation(root)) {
+        refreshContinuationTeamSignals(root, teamContinuationPayload(next), listTasks(root), listInbox(root), 'operator_team_message', `team message ${message.id}`);
+    }
+    else {
+        touchContinuationActivity(root, 'operator_team_message');
+    }
+    return next;
+}
+export function acknowledgeTeamMessage(root, executorId, messageId) {
+    ensureLayout(root);
+    const team = load(root);
+    if (!team)
+        return null;
+    const executor = team.executors.find((entry) => entry.id === executorId);
+    if (!executor)
+        return null;
+    executor.pendingInjectedMessageIds = executor.pendingInjectedMessageIds.filter((id) => id !== messageId);
+    if (executor.lastInjectedTurnMarker === messageId) {
+        executor.lastInjectedTurnMarker = executor.pendingInjectedMessageIds.at(-1) ?? null;
+    }
+    const message = team.messages.find((entry) => entry.id === messageId);
+    if (message) {
+        updateInboxItems(root, (item) => item.status === 'open'
+            && item.subject === message.subject
+            && item.body === message.body
+            && item.from === message.from
+            && item.to === message.to
+            && item.kind === (message.kind === 'review' ? 'review' : 'inbox'), 'acknowledged');
+    }
+    appendLedger(root, {
+        kind: 'executor',
+        action: 'team_message_ack',
+        detail: `${executorId} acknowledged ${messageId}`,
+        executorId,
+        metadata: { messageId },
+    });
+    acknowledgeContinuationFollowUp(root, {
+        dedupeKey: buildTeamMessageFollowUpDedupeKey(team.id, messageId),
+        reason: `executor ${executorId} acknowledged ${messageId}`,
+        source: 'operator_team_message_ack',
+    });
+    const next = save(root, team);
+    if (teamLaneOwnsContinuation(root)) {
+        refreshContinuationTeamSignals(root, teamContinuationPayload(next), listTasks(root), listInbox(root), 'operator_team_message_ack', `team message ack ${messageId}`);
+    }
+    else {
+        touchContinuationActivity(root, 'operator_team_message_ack');
+    }
+    return next;
+}
+export function readTeamLogs(root, executorId, limit = 50) {
+    try {
+        // best effort — log file may not yet exist if executor has never been active
+        return execFileSync('sh', ['-lc', `tail -n ${limit} "${teamLogFile(root, executorId)}"`], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function readTeamInbox(root) {
+    return listInbox(root);
+}
+export function listTeamTasks(root, filters = {}) {
+    return listTasks(root).filter((task) => {
+        if (task.kind !== 'team')
+            return false;
+        if (filters.status && task.status !== filters.status)
+            return false;
+        if (filters.owner && task.owner !== filters.owner)
+            return false;
+        return true;
+    });
+}
+export async function awaitTeamState(root, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const pollMs = options.pollMs ?? 250;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const team = readTeam(root);
+        if (!team)
+            return null;
+        if (!options.taskId)
+            return team;
+        const task = getTask(root, options.taskId);
+        if (task && ['review', 'completed', 'blocked', 'failed'].includes(task.status)) {
+            return team;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return readTeam(root);
+}
+export function queueTeamTask(root, title, owner = 'operator') {
+    ensureLayout(root);
+    const task = createTask(root, { title, kind: 'team', priority: 'high' });
+    enqueueTeamTask(root, task.id);
+    pushInboxItem(root, {
+        kind: 'inbox',
+        subject: 'Task queued',
+        body: `${title} queued by ${owner}`,
+        taskId: task.id,
+        from: owner,
+    });
+    return task;
+}
+/**
+ * Reads executor.pendingInjectedMessageIds, resolves the corresponding messages
+ * from team.messages, and returns them as structured content to be prepended to
+ * the member's next prompt.
+ *
+ * Called at turn-build time to surface any pending mailbox messages before
+ * the executor's task payload.
+ */
+export function buildMemberTurnInjection(executor, team) {
+    if (executor.pendingInjectedMessageIds.length === 0) {
+        return { messages: [] };
+    }
+    const pendingSet = new Set(executor.pendingInjectedMessageIds);
+    const messages = team.messages
+        .filter((msg) => pendingSet.has(msg.id))
+        .map((msg) => ({
+        id: msg.id,
+        subject: msg.subject,
+        body: msg.body,
+        kind: msg.kind,
+        from: msg.from,
+    }));
+    return { messages };
+}
+export function heartbeatTeamExecutor(root, executorId, note) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state)
+        return null;
+    const executors = state.executors.map((executor) => {
+        if (executor.id !== executorId)
+            return executor;
+        appendExecutorLog(root, executorId, `heartbeat${note ? ` ${note}` : ''}`);
+        return {
+            ...executor,
+            lastHeartbeatAt: now(),
+            status: (executor.status === 'stale' ? (executor.assignedTaskIds.length ? 'busy' : 'idle') : executor.status),
+        };
+    });
+    appendLedger(root, { kind: 'executor', action: 'executor_heartbeat', detail: `Heartbeat from ${executorId}`, executorId });
+    const next = save(root, { ...state, executors });
+    const hb = next.executors.find((e) => e.id === executorId);
+    if (hb?.continuationId) {
+        try {
+            touchDelegatedSession(root, hb.continuationId, { source: 'operator_team_heartbeat' });
+        }
+        catch {
+            // executor may predate delegated-session registry
+        }
+    }
+    return next;
+}
+//# sourceMappingURL=index.js.map