@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/app/collab-resources.js

@@ -0,0 +1,278 @@
+import path from 'node:path';
+import { collaborationResourceRequestSchema, } from '../schemas/collaboration.js';
+import { activeClaims, claimResources, checkClaimParticipant, DomainLockHeldError, listDomainRecords, releaseClaim, } from '../collab/resources.js';
+import { readBoundedFile } from './bounded-file.js';
+import { assertTaskStoreCurrent, openTaskStore, validateDomainMutationPaths, validateDomainTaskState, } from './collab-task-store.js';
+export const COLLAB_RESOURCES_SCHEMA = 'pappra/collaboration-resources/1';
+const MAX_REQUEST_BYTES = 1024 * 1024;
+const MAX_RESOURCE_TASKS = 100;
+const MAX_RESOURCE_CLAIMS = 500;
+function invalidRequest(message, nextAction) {
+    return {
+        ok: false,
+        code: 'invalid_request',
+        message,
+        nextAction,
+    };
+}
+/**
+ * Read and strictly validate one bounded resource request. Diagnostic text only
+ * names field paths/codes and never echoes request body values.
+ */
+export function loadResourceRequest(file, expectedAction) {
+    if (!path.isAbsolute(file)) {
+        return invalidRequest('Resource request path must be absolute.', 'Pass an absolute request JSON path.');
+    }
+    const read = readBoundedFile(file, MAX_REQUEST_BYTES);
+    if (!read.ok) {
+        return invalidRequest('Resource request must be a readable regular JSON file no larger than 1 MiB.', 'Inspect the request path and file kind; nothing was written.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.text);
+    }
+    catch {
+        return invalidRequest('Resource request is not valid JSON.', 'Rewrite the request as strict JSON; nothing was written.');
+    }
+    const validated = collaborationResourceRequestSchema.safeParse(parsed);
+    if (!validated.success) {
+        const issues = validated.error.issues
+            .slice(0, 8)
+            .map((issue) => {
+            const field = issue.path.length ? issue.path.join('.') : '(root)';
+            return `${field}:${issue.code}`;
+        })
+            .join(', ');
+        return invalidRequest(`Resource request does not match the strict schema (${issues || 'invalid shape'}).`, 'Fix the request schema; nothing was written.');
+    }
+    if (validated.data.action !== expectedAction) {
+        return invalidRequest('Resource request action does not match the invoked resource command.', `Use a ${expectedAction} request; nothing was written.`);
+    }
+    return { ok: true, value: { request: validated.data, path: file } };
+}
+function identityOf(holder) {
+    return {
+        agent_id: holder.agent_id,
+        session_id: holder.session_id,
+        harness: holder.harness ?? null,
+    };
+}
+function requestSummary(request) {
+    if (request.action === 'claim') {
+        return {
+            action: request.action,
+            holder: identityOf(request.holder),
+            access: request.access,
+            resource_count: request.resources.length,
+            include_shared_git: request.include_shared_git === true,
+            subtask_id: request.subtask_id ?? null,
+            attempt: request.attempt ?? null,
+        };
+    }
+    return {
+        action: request.action,
+        holder: identityOf(request.holder),
+        claim_id: request.claim_id,
+    };
+}
+async function openForResource(taskRoot, action) {
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        return opened;
+    if (action === 'claim') {
+        const domainState = validateDomainTaskState(opened.value.domainRoot);
+        if (domainState)
+            return domainState;
+        const mutationPaths = validateDomainMutationPaths(opened.value.domainRoot);
+        if (mutationPaths)
+            return mutationPaths;
+    }
+    return opened;
+}
+async function revalidateForApply(opened, action) {
+    const changed = await assertTaskStoreCurrent(opened);
+    if (changed !== null)
+        return changed;
+    if (action === 'claim') {
+        const domainState = validateDomainTaskState(opened.domainRoot);
+        if (domainState)
+            return domainState;
+        return validateDomainMutationPaths(opened.domainRoot);
+    }
+    return null;
+}
+export async function planResourceRequest(taskRoot, request) {
+    const opened = await openForResource(taskRoot, request.action);
+    if (!opened.ok)
+        return opened;
+    if (request.action === 'claim') {
+        const participant = checkClaimParticipant(opened.value.record, identityOf(request.holder), request.subtask_id ?? null, request.attempt ?? null);
+        if (!participant.ok)
+            return {
+                ok: false,
+                code: participant.reason,
+                message: 'The resource holder is not authorized for an active task assignment.',
+                nextAction: 'Use the current coordinator identity or the matching active assignment and holder.',
+            };
+    }
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_RESOURCES_SCHEMA,
+            ok: true,
+            action: request.action,
+            applied: false,
+            status: 'planned',
+            task_root: opened.value.taskRoot,
+            task_id: opened.value.record.task_id,
+            domain_root: opened.value.domainRoot,
+            request: requestSummary(request),
+            limits: ['plan_validates_request_and_namespace_only', 'no_reservation'],
+        },
+    };
+}
+export async function applyResourceRequest(taskRoot, request) {
+    const opened = await openForResource(taskRoot, request.action);
+    if (!opened.ok)
+        return opened;
+    const changed = await revalidateForApply(opened.value, request.action);
+    if (changed)
+        return changed;
+    if (request.action === 'claim') {
+        const resources = request.resources;
+        let outcome;
+        try {
+            outcome = claimResources(opened.value.taskRoot, {
+                resources,
+                access: request.access,
+                holder: identityOf(request.holder),
+                note: request.note ?? null,
+                includeSharedGit: request.include_shared_git === true,
+                subtaskId: request.subtask_id ?? null,
+                attempt: request.attempt ?? null,
+                requireAssignedHolder: true,
+            });
+        }
+        catch (error) {
+            if (error instanceof DomainLockHeldError)
+                return {
+                    ok: false,
+                    code: 'domain_lock_held',
+                    message: 'The resource-domain lock is held; no claim was made.',
+                    nextAction: 'Retry explicitly after the current domain operation finishes; nothing was mutated.',
+                };
+            return {
+                ok: false,
+                code: 'resource_operation_failed',
+                message: 'The resource claim could not be completed.',
+                nextAction: 'Inspect the task/domain state; no claim is promised.',
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                schema: COLLAB_RESOURCES_SCHEMA,
+                action: 'claim',
+                applied: outcome.ok,
+                task_root: opened.value.taskRoot,
+                task_id: opened.value.record.task_id,
+                ...outcome,
+            },
+        };
+    }
+    let outcome;
+    try {
+        outcome = releaseClaim(opened.value.taskRoot, {
+            claimId: request.claim_id,
+            holder: identityOf(request.holder),
+            ...(request.reason === undefined || request.reason === null
+                ? {}
+                : { reason: request.reason }),
+        });
+    }
+    catch {
+        return {
+            ok: false,
+            code: 'resource_operation_failed',
+            message: 'The resource release could not be completed.',
+            nextAction: 'Inspect the task state; nothing is promised to have been released.',
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_RESOURCES_SCHEMA,
+            action: 'release',
+            applied: outcome.ok,
+            task_root: opened.value.taskRoot,
+            task_id: opened.value.record.task_id,
+            ...outcome,
+        },
+    };
+}
+export async function listTaskResources(taskRoot) {
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        return opened;
+    const domainState = validateDomainTaskState(opened.value.domainRoot);
+    if (domainState)
+        return domainState;
+    const records = listDomainRecords(opened.value.domainRoot);
+    const unreadable = records
+        .filter((record) => record.__unreadable)
+        .map((record) => record.task_id);
+    const tasks = records
+        .map((record) => ({
+        task_id: record.task_id,
+        claims: activeClaims(record).map((claim) => ({
+            ...claim,
+            task_id: record.task_id,
+        })),
+    }))
+        .filter((task) => task.claims.length > 0);
+    const claimCount = tasks.reduce((total, task) => total + task.claims.length, 0);
+    let remainingClaims = MAX_RESOURCE_CLAIMS;
+    let emittedClaims = 0;
+    const taskRows = [];
+    for (const task of tasks) {
+        if (taskRows.length >= MAX_RESOURCE_TASKS || remainingClaims <= 0)
+            break;
+        const take = Math.min(task.claims.length, remainingClaims);
+        if (take === 0)
+            continue;
+        taskRows.push({
+            ...task,
+            claims: task.claims.slice(0, take),
+        });
+        remainingClaims -= take;
+        emittedClaims += take;
+    }
+    const omittedClaims = claimCount - emittedClaims;
+    const omittedTasks = tasks.length - taskRows.length;
+    const omittedUnreadable = Math.max(0, unreadable.length - MAX_RESOURCE_TASKS);
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_RESOURCES_SCHEMA,
+            ok: unreadable.length === 0,
+            action: 'list',
+            state: unreadable.length ? 'unknown' : 'known',
+            domain_id: opened.value.record.domain_id,
+            domain_root: opened.value.domainRoot,
+            tasks: taskRows,
+            unreadable_tasks: unreadable.slice(0, MAX_RESOURCE_TASKS),
+            counts: {
+                tasks: tasks.length,
+                claims: claimCount,
+                unreadable_tasks: unreadable.length,
+            },
+            omitted: {
+                tasks: omittedTasks,
+                claims: omittedClaims,
+                unreadable_tasks: omittedUnreadable,
+            },
+            truncated: omittedClaims > 0 || omittedTasks > 0 || omittedUnreadable > 0,
+            limits: ['reported_domain_claims_only', 'unreadable_state_is_not_empty'],
+        },
+    };
+}

package/dist/app/collab-role-events.d.ts

@@ -0,0 +1,22 @@
+import { tickRoleOrchestration, type RoleOrchestrationRequest, type RoleOrchestrationResult } from './collab-role-orchestration.js';
+import { openTaskStore, assertTaskStoreCurrent } from './collab-task-store.js';
+export declare const ROLE_RUN_REQUEST_SCHEMA = "pappra/collab-role-orchestration-request/1";
+export declare function loadRoleRunRequest(file: string): RoleOrchestrationRequest;
+export interface RoleEventWatcher {
+    refresh(): Promise<void>;
+    status(): {
+        readonly result: RoleOrchestrationResult | null;
+        readonly error: string | null;
+    };
+    close(): Promise<void>;
+}
+export interface RoleEventDependencies {
+    readonly openTaskStore?: typeof openTaskStore;
+    readonly assertTaskStoreCurrent?: typeof assertTaskStoreCurrent;
+    readonly tick?: typeof tickRoleOrchestration;
+}
+/**
+ * Native session events and authoritative task-store changes drive one bounded tick.
+ * Watch subscriptions follow request changes. The orchestration journal is never a cause.
+ */
+export declare function watchRoleOrchestration(requestFile: string, onResult?: (result: RoleOrchestrationResult) => void, deps?: RoleEventDependencies): Promise<RoleEventWatcher>;

package/dist/app/collab-role-events.js

@@ -0,0 +1,329 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from './bounded-file.js';
+import { tickRoleOrchestration, } from './collab-role-orchestration.js';
+import { openTaskStore, assertTaskStoreCurrent } from './collab-task-store.js';
+import { canonicalJson } from '../collab/envelope.js';
+import { managedPiRepairDependencies } from './managed-pi-repair-stop.js';
+export const ROLE_RUN_REQUEST_SCHEMA = 'pappra/collab-role-orchestration-request/1';
+export function loadRoleRunRequest(file) {
+    const loaded = readBoundedFile(file, 1024 * 1024);
+    if (!loaded.ok)
+        throw new Error(`role_request_${loaded.code}`);
+    let value;
+    try {
+        value = JSON.parse(loaded.text);
+    }
+    catch {
+        throw new Error('role_request_invalid_json');
+    }
+    if (typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value) ||
+        !('schema' in value) ||
+        value.schema !== ROLE_RUN_REQUEST_SCHEMA ||
+        !('role_plan' in value) ||
+        !('execution' in value) ||
+        !('limits' in value) ||
+        !('event_id' in value) ||
+        !('journal_file' in value))
+        throw new Error('role_request_invalid');
+    return value;
+}
+function safeDirectory(directory) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        fs.realpathSync(directory) !== directory)
+        throw new Error('role_event_directory_redirected');
+    return stat;
+}
+function buildWatchNames(requestFile, taskRoot, request, pins) {
+    const journalFile = path.resolve(request.journal_file);
+    const inputs = [
+        requestFile,
+        path.join(taskRoot, 'task.json'),
+        ...request.execution.capability_cards.map((card) => card.capabilities_file),
+    ];
+    const watchNames = new Map();
+    for (const input of inputs) {
+        if (typeof input !== 'string' || !path.isAbsolute(input))
+            throw new Error('role_event_path_not_absolute');
+        const absolute = path.resolve(input);
+        if (absolute === journalFile)
+            throw new Error('role_event_journal_input_conflict');
+        const directory = path.dirname(absolute);
+        const stat = safeDirectory(directory);
+        const pin = pins.get(directory);
+        if (pin && (pin.device !== stat.dev || pin.inode !== stat.ino))
+            throw new Error('role_event_directory_changed');
+        if (!pin)
+            pins.set(directory, { device: stat.dev, inode: stat.ino });
+        const names = watchNames.get(directory) ?? new Set();
+        names.add(path.basename(absolute));
+        watchNames.set(directory, names);
+    }
+    return watchNames;
+}
+function sameNames(left, right) {
+    return left.size === right.size && [...left].every((name) => right.has(name));
+}
+/**
+ * Native session events and authoritative task-store changes drive one bounded tick.
+ * Watch subscriptions follow request changes. The orchestration journal is never a cause.
+ */
+export async function watchRoleOrchestration(requestFile, onResult = () => { }, deps = {}) {
+    if (!path.isAbsolute(requestFile))
+        throw new Error('role_event_request_path_not_absolute');
+    const openStore = deps.openTaskStore ?? openTaskStore;
+    const assertCurrent = deps.assertTaskStoreCurrent ?? assertTaskStoreCurrent;
+    const tick = deps.tick ?? tickRoleOrchestration;
+    const initial = loadRoleRunRequest(requestFile);
+    const opened = await openStore(initial.execution.task_root);
+    if (!opened.ok)
+        throw new Error('role_event_task_unavailable');
+    const task = opened.value;
+    const taskRoot = task.taskRoot;
+    const messagesDirectory = task.messagesDirectory;
+    if (path.resolve(initial.execution.task_root) !== path.resolve(taskRoot))
+        throw new Error('role_event_task_root_mismatch');
+    const messagesRelative = path.relative(taskRoot, messagesDirectory);
+    if (messagesRelative === '' ||
+        messagesRelative.startsWith('..') ||
+        path.isAbsolute(messagesRelative))
+        throw new Error('role_event_task_namespace_mismatch');
+    const taskRootIdentity = safeDirectory(taskRoot);
+    const messagesDirectoryIdentity = safeDirectory(messagesDirectory);
+    const namespacePins = {
+        taskRoot: { device: taskRootIdentity.dev, inode: taskRootIdentity.ino },
+        messagesDirectory: {
+            device: messagesDirectoryIdentity.dev,
+            inode: messagesDirectoryIdentity.ino,
+        },
+    };
+    const directoryPins = new Map();
+    const watchers = new Map();
+    let closed = false;
+    let running = false;
+    let pending = false;
+    let last = null;
+    let lastError = null;
+    let lastCause = null;
+    let retryCause = null;
+    let lockRetries = 0;
+    let retryTimer = null;
+    let subscriptionTimer = null;
+    let activeJournalFile = path.resolve(initial.journal_file);
+    let active = Promise.resolve();
+    const syncWatchers = (request) => {
+        let changed = false;
+        const activeDirectories = new Set([
+            path.dirname(path.resolve(requestFile)),
+            path.dirname(path.join(taskRoot, 'task.json')),
+            ...request.execution.capability_cards.map((card) => path.dirname(path.resolve(card.capabilities_file))),
+        ]);
+        for (const directory of directoryPins.keys()) {
+            if (!activeDirectories.has(directory))
+                directoryPins.delete(directory);
+        }
+        const desired = buildWatchNames(requestFile, taskRoot, request, directoryPins);
+        activeJournalFile = path.resolve(request.journal_file);
+        for (const [directory, current] of watchers) {
+            const names = desired.get(directory);
+            if (!names) {
+                current.watcher.close();
+                watchers.delete(directory);
+                changed = true;
+            }
+            else if (!sameNames(current.names, names)) {
+                current.names = names;
+                changed = true;
+            }
+        }
+        for (const [directory, names] of desired) {
+            if (watchers.has(directory))
+                continue;
+            const entry = {
+                watcher: fs.watch(directory, (_event, name) => {
+                    if (closed)
+                        return;
+                    const observedName = name?.toString() ?? null;
+                    const ownJournal = activeJournalFile;
+                    if (observedName !== null &&
+                        path.resolve(directory, observedName) === ownJournal)
+                        return;
+                    if (observedName === null || entry.names.has(observedName))
+                        void refresh();
+                }),
+                names,
+            };
+            entry.watcher.on('error', () => {
+                lastError = 'role_event_watch_failed';
+            });
+            watchers.set(directory, entry);
+            changed = true;
+        }
+        if (changed) {
+            if (subscriptionTimer)
+                clearTimeout(subscriptionTimer);
+            // Directory subscriptions can miss writes while the OS attaches them.
+            // Reconcile once after rebinding; unchanged causes never dispatch again.
+            subscriptionTimer = setTimeout(() => {
+                subscriptionTimer = null;
+                if (!closed)
+                    void refresh();
+            }, 50);
+            subscriptionTimer.unref();
+        }
+    };
+    const refresh = () => {
+        if (closed)
+            return active;
+        pending = true;
+        if (running)
+            return active;
+        running = true;
+        active = (async () => {
+            try {
+                while (pending && !closed) {
+                    pending = false;
+                    const request = loadRoleRunRequest(requestFile);
+                    if (path.resolve(request.execution.task_root) !== path.resolve(taskRoot))
+                        throw new Error('role_event_task_changed');
+                    syncWatchers(request);
+                    for (const [directory, pin] of directoryPins) {
+                        const now = safeDirectory(directory);
+                        if (now.dev !== pin.device || now.ino !== pin.inode)
+                            throw new Error('role_event_directory_changed');
+                    }
+                    const current = await openStore(taskRoot);
+                    if (!current.ok)
+                        throw new Error('role_event_task_unavailable');
+                    if (path.resolve(current.value.taskRoot) !== path.resolve(taskRoot) ||
+                        path.resolve(current.value.messagesDirectory) !==
+                            path.resolve(messagesDirectory))
+                        throw new Error('role_event_task_namespace_changed');
+                    const currentTaskRoot = safeDirectory(current.value.taskRoot);
+                    const currentMessagesDirectory = safeDirectory(current.value.messagesDirectory);
+                    if (currentTaskRoot.dev !== namespacePins.taskRoot.device ||
+                        currentTaskRoot.ino !== namespacePins.taskRoot.inode ||
+                        currentMessagesDirectory.dev !==
+                            namespacePins.messagesDirectory.device ||
+                        currentMessagesDirectory.ino !==
+                            namespacePins.messagesDirectory.inode)
+                        throw new Error('role_event_task_namespace_changed');
+                    const unsafe = await assertCurrent(current.value);
+                    if (unsafe)
+                        throw new Error('role_event_task_store_changed');
+                    const record = current.value.record;
+                    const cardDigests = request.execution.capability_cards.map((card) => {
+                        const bytes = readBoundedFile(card.capabilities_file, 1024 * 1024);
+                        return {
+                            assignment: card.assignment_id,
+                            digest: bytes.ok ? bytes.digest : bytes.code,
+                        };
+                    });
+                    const cause = crypto
+                        .createHash('sha256')
+                        .update(canonicalJson({
+                        request: {
+                            role_plan: request.role_plan,
+                            execution: request.execution,
+                            journal_file: request.journal_file,
+                            limits: request.limits,
+                            repair_policy: request.repair_policy ?? null,
+                        },
+                        coordinator: record.coordinator ?? null,
+                        attempts: record.attempts ?? [],
+                        messages: record.messages ?? [],
+                        results: record.results ?? [],
+                        claims: record.claims ?? [],
+                        uncertainty: record.uncertainty ?? [],
+                        dispatch_frozen: record.dispatch_frozen ?? false,
+                        managed_runtimes: record.managed_pi_runtime_registry ?? null,
+                        cards: cardDigests,
+                    }))
+                        .digest('hex');
+                    if (cause === lastCause)
+                        continue;
+                    lastCause = cause;
+                    const repair = managedPiRepairDependencies(request);
+                    last = await tick({
+                        ...request,
+                        // Assigned-but-undispatched work was previously mistaken for
+                        // active execution. Reconcile it under the corrected scheduler;
+                        // durable work intents still prevent any native redelivery.
+                        event_id: `task-event-v2-${cause}`,
+                    }, repair ? { repair } : {});
+                    lastError = null;
+                    onResult(last);
+                    if (last.diagnostics.includes('journal_lock_present_or_busy')) {
+                        if (retryCause !== cause) {
+                            retryCause = cause;
+                            lockRetries = 0;
+                        }
+                        if (lockRetries < 2 && !retryTimer) {
+                            lockRetries++;
+                            // This outcome reserved no tick and caused no native effect.
+                            // A stale lock remains visible after the bounded retries.
+                            retryTimer = setTimeout(() => {
+                                retryTimer = null;
+                                if (!closed) {
+                                    lastCause = null;
+                                    void refresh();
+                                }
+                            }, 50 * lockRetries);
+                            retryTimer.unref();
+                        }
+                    }
+                    else {
+                        if (retryTimer)
+                            clearTimeout(retryTimer);
+                        retryTimer = null;
+                        retryCause = null;
+                        lockRetries = 0;
+                    }
+                }
+            }
+            catch {
+                // Never publish filesystem paths, serialized requests, or raw exception details.
+                lastError = 'role_event_reconciliation_failed';
+            }
+            finally {
+                running = false;
+                if (pending && !closed)
+                    void refresh();
+            }
+        })();
+        return active;
+    };
+    try {
+        syncWatchers(initial);
+        await refresh();
+    }
+    catch {
+        if (subscriptionTimer)
+            clearTimeout(subscriptionTimer);
+        for (const entry of watchers.values())
+            entry.watcher.close();
+        throw new Error('role_event_watch_initialization_failed');
+    }
+    return {
+        refresh,
+        status: () => ({ result: last, error: lastError }),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            if (retryTimer)
+                clearTimeout(retryTimer);
+            if (subscriptionTimer)
+                clearTimeout(subscriptionTimer);
+            for (const entry of watchers.values())
+                entry.watcher.close();
+            watchers.clear();
+            await active;
+        },
+    };
+}

package/dist/app/collab-role-orchestration.d.ts

@@ -0,0 +1,53 @@
+import { type RolePlanAggregation, type RolePlanRequest } from './collab-role-plan.js';
+import { type WorkPlanInspectionOptions, type WorkPlanReport } from './collab-work-plan.js';
+import { type WorkExecutionOptions, type WorkExecutionReport, type WorkExecutionAdapter } from './collab-work-execution.js';
+import { type RoleRepairDependencies, type RoleRepairPolicy } from './collab-role-repair.js';
+export declare const COLLAB_ROLE_ORCHESTRATION_SCHEMA = "pappra/collab-role-orchestration/1";
+export interface RoleOrchestrationLimits {
+    /** Maximum distinct evidence events (ticks) for this plan. */
+    readonly max_rounds: number;
+    /** Conservative maximum dispatch reservations across all ticks for this plan. */
+    readonly max_actions: number;
+    /** Maximum approved assignment attempt for rejected-node repair. */
+    readonly max_attempts: number;
+}
+export interface RoleOrchestrationRequest {
+    readonly role_plan: RolePlanRequest;
+    readonly execution: WorkExecutionOptions['request'];
+    /** Stable ID supplied by the triggering session event; repeated IDs never run twice. */
+    readonly event_id: string;
+    /** Task-local durable receipt file, e.g. `<task_root>/role-orchestration.json`. */
+    readonly journal_file: string;
+    readonly limits: RoleOrchestrationLimits;
+    /** Explicitly pre-authorized repair transitions; omitted requests retain legacy behavior. */
+    readonly repair_policy?: RoleRepairPolicy;
+}
+export type RoleOrchestrationStatus = 'dispatched' | 'waiting' | 'accepted' | 'repaired' | 'repair-required' | 'repair-exhausted' | 'blocked' | 'reconciliation-required' | 'budget-exhausted' | 'duplicate';
+export interface RoleOrchestrationResult {
+    readonly schema: typeof COLLAB_ROLE_ORCHESTRATION_SCHEMA;
+    readonly status: RoleOrchestrationStatus;
+    readonly event_id: string;
+    readonly plan_id: string;
+    readonly round: number | null;
+    readonly reserved_actions: number;
+    readonly prior_outcome: string | null;
+    readonly aggregate: RolePlanAggregation | null;
+    readonly execution: WorkExecutionReport | null;
+    /** Returned for the root event driver to persist with its guarded-CAS request writer. */
+    readonly updatedRequest: RoleOrchestrationRequest | null;
+    readonly diagnostics: readonly string[];
+}
+export interface RoleOrchestrationDependencies {
+    readonly inspect?: (options: WorkPlanInspectionOptions) => Promise<WorkPlanReport>;
+    readonly execute?: (options: WorkExecutionOptions, deps?: {
+        readonly adapter?: WorkExecutionAdapter;
+    }) => Promise<WorkExecutionReport>;
+    readonly execution_adapter?: WorkExecutionAdapter;
+    readonly repair?: RoleRepairDependencies;
+}
+/**
+ * Advances one explicit session-event tick over the existing role-plan and WorkPlan state.
+ * The durable journal reserves the event and conservative action budget before execution;
+ * the task record, registered envelopes, and WorkPlan evaluator remain the only authority.
+ */
+export declare function tickRoleOrchestration(request: RoleOrchestrationRequest, deps?: RoleOrchestrationDependencies): Promise<RoleOrchestrationResult>;