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

package/dist/app/managed-pi-bootstrap-admission.d.ts

@@ -0,0 +1,14 @@
+import type { PiBootstrapConfig } from '../hosts/integration/bootstrap-config.js';
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+import { type BoundManagedPiExecutionScope } from './managed-pi-transition-host.js';
+import type { ManagedPiExecutionScope } from './collab-session-transition.js';
+/** A receiver is controller-owned at launch, but task ownership binds only after the real transfer. */
+export declare function watchManagedPiBootstrapAdmission(controller: ManagedPiSdkSessionController, config: PiBootstrapConfig, onBound: (binding: BoundManagedPiExecutionScope) => Promise<void>): Promise<{
+    refresh: () => Promise<void>;
+    status: () => {
+        state: "awaiting_idle" | "awaiting_transfer" | "bound" | "unavailable";
+        error: string | null;
+        scope: ManagedPiExecutionScope | null;
+    };
+    close(): Promise<void>;
+}>;

package/dist/app/managed-pi-bootstrap-admission.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import { createLocalTaskRecordReader } from '../hosts/integration/pi-bootstrap-runtime.js';
+import { decideBootstrapWrite } from '../hosts/integration/pi-bootstrap-guard.js';
+import { bindManagedPiExecutionScope, } from './managed-pi-transition-host.js';
+/** A receiver is controller-owned at launch, but task ownership binds only after the real transfer. */
+export async function watchManagedPiBootstrapAdmission(controller, config, onBound) {
+    const reader = createLocalTaskRecordReader(config.domainRoot, config.taskId);
+    const taskRoot = reader.read().task_root;
+    let closed = false;
+    let pending = false;
+    let active = null;
+    let binding = null;
+    let state = 'awaiting_transfer';
+    let error = null;
+    const refresh = () => {
+        if (closed || binding)
+            return active ?? Promise.resolve();
+        pending = true;
+        if (active)
+            return active;
+        active = (async () => {
+            try {
+                while (pending && !closed && !binding) {
+                    pending = false;
+                    const native = controller.observe();
+                    const record = reader.read();
+                    if (!decideBootstrapWrite(record, config.guard, native.native.sessionId)
+                        .allow) {
+                        state = 'awaiting_transfer';
+                        continue;
+                    }
+                    const inventory = await controller.inventory();
+                    if (inventory.completeness !== 'complete' ||
+                        inventory.inflight.length ||
+                        inventory.pending_approvals.length ||
+                        inventory.pending_messages?.length !== 0) {
+                        state = 'awaiting_idle';
+                        continue;
+                    }
+                    const scope = {
+                        schema: 'pappra/managed-pi-execution-scope/1',
+                        task_id: config.taskId,
+                        task_root: taskRoot,
+                        session_id: native.native.sessionId,
+                        cwd: native.cwd,
+                        subtask_id: config.guard.subtaskId,
+                        attempt: config.guard.attempt,
+                        owner_epoch: config.guard.coordinatorEpoch,
+                        claim_epochs: config.guard.claims.map((claim) => ({
+                            claim_id: claim.claimId,
+                            resource_epoch: claim.originalResourceEpoch + 1,
+                        })),
+                    };
+                    const candidate = await bindManagedPiExecutionScope({
+                        controller,
+                        scope,
+                    });
+                    await onBound(candidate);
+                    binding = candidate;
+                    state = 'bound';
+                    error = null;
+                }
+            }
+            catch (cause) {
+                state = 'unavailable';
+                error =
+                    cause instanceof Error
+                        ? cause.message
+                        : 'managed_bootstrap_admission_unavailable';
+            }
+        })().finally(() => {
+            active = null;
+        });
+        return active;
+    };
+    const watcher = fs.watch(taskRoot, (_event, name) => {
+        if (name === null || name.toString() === 'task.json')
+            void refresh();
+    });
+    watcher.on('error', () => {
+        state = 'unavailable';
+        error = 'managed_bootstrap_watch_failed';
+    });
+    const unsubscribe = controller.subscribe((event) => {
+        if (typeof event === 'object' &&
+            event !== null &&
+            'type' in event &&
+            (event.type === 'agent_settled' || event.type === 'resources_ready'))
+            setImmediate(() => {
+                void refresh();
+            }).unref();
+    });
+    await refresh();
+    return {
+        refresh,
+        status: () => ({ state, error, scope: binding?.scope ?? null }),
+        async close() {
+            closed = true;
+            watcher.close();
+            unsubscribe();
+            await active;
+        },
+    };
+}

package/dist/app/managed-pi-bootstrap-refresh.d.ts

@@ -0,0 +1,10 @@
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+import { type ManagedPiReadinessConfig } from './managed-pi-readiness.js';
+/** Refresh native evidence and resolve an unspecified caller from this owned source. */
+export declare function refreshManagedBootstrapAdmission(runtime: ManagedPiSdkSessionController, readiness: ManagedPiReadinessConfig, original: {
+    readonly ref: string;
+    readonly digest: string;
+}): Promise<{
+    readonly ref: string;
+    readonly digest: string;
+}>;

package/dist/app/managed-pi-bootstrap-refresh.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../collab/envelope.js';
+import { loadVisibleBootstrapRequest } from './collab-bootstrap.js';
+import { publishManagedPiReadiness, } from './managed-pi-readiness.js';
+import { readBoundedFile } from './bounded-file.js';
+/** Refresh native evidence and resolve an unspecified caller from this owned source. */
+export async function refreshManagedBootstrapAdmission(runtime, readiness, original) {
+    const loaded = loadVisibleBootstrapRequest(original.ref);
+    if (!loaded.ok || loaded.value.digest !== original.digest)
+        throw new Error('bootstrap_refresh_template_changed');
+    const request = loaded.value.request;
+    if (!request.managed_runtime ||
+        request.admission.capability_card_ref !== readiness.cardFile)
+        throw new Error('bootstrap_refresh_card_not_authorized');
+    const observation = runtime.observe();
+    if (observation.cwd !== request.target.cwd ||
+        observation.native.modelObservation.provider !== 'openrouter' ||
+        typeof observation.native.modelObservation.model !== 'string')
+        throw new Error('bootstrap_refresh_native_identity_mismatch');
+    runtime.publishResourcesReady(true);
+    if (!runtime.metadataFile)
+        throw new Error('bootstrap_refresh_source_metadata_missing');
+    const status = publishManagedPiReadiness(readiness, {
+        sessionId: observation.native.sessionId,
+        cwd: observation.cwd,
+        metadataFile: runtime.metadataFile,
+        expectedProvider: 'openrouter',
+        expectedModel: observation.native.modelObservation.model,
+    });
+    if (status.preflight !== 'ready')
+        throw new Error('bootstrap_refresh_not_ready');
+    const card = readBoundedFile(readiness.cardFile, 1024 * 1024);
+    if (!card.ok)
+        throw new Error('bootstrap_refresh_card_unreadable');
+    const updated = {
+        ...request,
+        ...(request.caller.pane_id == null && observation.native.paneId
+            ? {
+                caller: { ...request.caller, pane_id: observation.native.paneId },
+            }
+            : {}),
+        admission: { ...request.admission, capability_card_digest: card.digest },
+    };
+    const bytes = `${canonicalJson(updated)}\n`;
+    const digest = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+    const file = `${original.ref}.admitted-${digest.slice(7, 23)}.json`;
+    const parent = fs.lstatSync(path.dirname(file));
+    if (!parent.isDirectory() ||
+        parent.isSymbolicLink() ||
+        parent.mode & 0o077 ||
+        fs.realpathSync(path.dirname(file)) !== path.dirname(file))
+        throw new Error('bootstrap_refresh_parent_not_private');
+    if (fs.lstatSync(file, { throwIfNoEntry: false })) {
+        const existing = readBoundedFile(file, 64 * 1024);
+        if (!existing.ok || existing.digest !== digest)
+            throw new Error('bootstrap_refresh_pin_conflict');
+    }
+    else {
+        const fd = fs.openSync(file, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, bytes);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const directory = fs.openSync(path.dirname(file), 'r');
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    return { ref: file, digest };
+}

package/dist/app/managed-pi-delivery.d.ts

@@ -0,0 +1,8 @@
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+type Runtime = Pick<ManagedPiSdkSessionController, 'observe' | 'snapshot' | 'submitInput'>;
+/** Only registered pointers in the runtime's launch-bound namespace become native input. */
+export declare function deliverManagedPiMessage(runtime: Runtime, request: Readonly<Record<string, unknown>>, authorization: {
+    readonly taskRoot: string;
+    readonly agentId: string;
+}): Promise<Readonly<Record<string, unknown>>>;
+export {};

package/dist/app/managed-pi-delivery.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { isTaskRecord } from '../collab/validation.js';
+import { openMessageTask, readRegisteredMessageSafe, assertMessageTaskCurrent, } from './collab-messages.js';
+import { buildNotificationText } from './collab-notify.js';
+import { routeExclusionFor } from './collab-route.js';
+import { readBoundedFile } from './bounded-file.js';
+const same = (a, b) => a?.agent_id === b.agent_id &&
+    a.session_id === b.session_id &&
+    a.harness === b.harness;
+/** Only registered pointers in the runtime's launch-bound namespace become native input. */
+export async function deliverManagedPiMessage(runtime, request, authorization) {
+    const refuse = (reason) => ({ ok: false, reason });
+    if (request.task_root !== authorization.taskRoot ||
+        typeof request.message_id !== 'string' ||
+        typeof request.digest !== 'string' ||
+        request.expected_session_id !== runtime.observe().native.sessionId)
+        return refuse('delivery_scope_mismatch');
+    const opened = await openMessageTask(authorization.taskRoot);
+    if (!opened.ok)
+        return refuse(opened.code);
+    const registered = await readRegisteredMessageSafe(opened.value, request.message_id);
+    if (!registered.ok)
+        return refuse(registered.code);
+    if (registered.value.digest !== request.digest)
+        return refuse('delivery_digest_mismatch');
+    if (await assertMessageTaskCurrent(opened.value))
+        return refuse('delivery_namespace_changed');
+    // No async seam follows the last namespace/record read and the native admission.
+    const latest = readBoundedFile(opened.value.recordFile, 8 * 1024 * 1024);
+    if (!latest.ok)
+        return refuse('delivery_namespace_changed');
+    let record;
+    try {
+        record = JSON.parse(latest.text);
+    }
+    catch {
+        return refuse('delivery_record_missing');
+    }
+    if (!isTaskRecord(record) ||
+        record.task_id !== opened.value.record.task_id ||
+        record.task_root !== opened.value.taskRoot ||
+        record.domain_root !== opened.value.record.domain_root ||
+        record.domain_id !== opened.value.record.domain_id ||
+        record.created_at !== opened.value.record.created_at)
+        return refuse('delivery_record_missing');
+    const latestMessage = readBoundedFile(registered.value.file, 1024 * 1024);
+    if (!latestMessage.ok || latestMessage.digest !== registered.value.digest)
+        return refuse('delivery_digest_mismatch');
+    const message = registered.value.message;
+    const live = runtime.observe();
+    if (message.to.harness !== 'pi' ||
+        message.to.agent_id !== authorization.agentId ||
+        message.to.session_id !== live.native.sessionId ||
+        (message.to.cwd !== undefined && message.to.cwd !== live.cwd) ||
+        message.owner_epoch !== record.coordinator?.owner_epoch)
+        return refuse('delivery_identity_stale');
+    for (const side of [message.from, message.to])
+        if (routeExclusionFor(record, side).state !== 'active')
+            return refuse('delivery_route_excluded');
+    if (message.subtask_id !== null || message.attempt !== null) {
+        const attempt = record.attempts.find((row) => row.subtask_id === message.subtask_id &&
+            row.attempt === message.attempt);
+        if (!attempt ||
+            attempt.closed_at ||
+            attempt.cancel_requested_at ||
+            [
+                'completed',
+                'failed',
+                'cancelled',
+                'canceled',
+                'awaiting_approval',
+                'blocked',
+            ].includes(attempt.state) ||
+            attempt.awaiting === 'approval' ||
+            attempt.owner_epoch !== message.owner_epoch ||
+            (message.body.input_revision !== undefined &&
+                message.body.input_revision !== attempt.input_revision))
+            return refuse('delivery_attempt_inactive');
+        if (!same(message.from, record.coordinator) &&
+            !same(message.from, attempt.assignee))
+            return refuse('delivery_sender_inactive');
+        if (record.claims.some((claim) => claim.subtask_id === attempt.subtask_id &&
+            claim.attempt === attempt.attempt &&
+            !claim.released_at &&
+            claim.cancel_pending))
+            return refuse('delivery_cancellation_pending');
+    }
+    else if (!same(message.from, record.coordinator))
+        return refuse('delivery_sender_inactive');
+    const inventory = runtime.snapshot().ownedRuntime;
+    if (inventory.extensionDialogs.completeness !== 'complete' ||
+        inventory.extensionDialogs.pending.length ||
+        inventory.queues.internal.activeSelector)
+        return refuse('delivery_approval_pending');
+    if (message.type === 'ASSIGN' && record.dispatch_frozen)
+        return refuse('delivery_dispatch_frozen');
+    const entry = record.messages.find((row) => row.message_id === message.message_id);
+    if (!entry ||
+        entry.content_digest !== message.content_digest ||
+        !['applied', 'recorded'].includes(entry.state))
+        return refuse('delivery_registration_stale');
+    const text = buildNotificationText({
+        taskId: record.task_id,
+        type: message.type,
+        messagePath: registered.value.file,
+        digest: registered.value.digest,
+    });
+    const id = `message-${createHash('sha256').update(`${authorization.taskRoot}\0${message.message_id}\0${registered.value.digest}`).digest('hex')}`;
+    return { ok: true, admission: runtime.submitInput(id, text) };
+}

package/dist/app/managed-pi-handoff-receiver.d.ts

@@ -0,0 +1,15 @@
+import type { PiBootstrapConfig } from '../hosts/integration/bootstrap-config.js';
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+/** Import verified continuity into the actual receiver before acknowledging receipt. */
+export declare function prepareManagedPiHandoffReceiver(runtime: ManagedPiSdkSessionController, config: PiBootstrapConfig, referenceFile: string, journalPath: string): Promise<{
+    priorSourceRetired(): boolean;
+    startWork(): void;
+    status: () => {
+        context_imported: boolean;
+        ack_registered: boolean;
+        work_admitted: boolean;
+        first_work_observed: boolean;
+        error: string | null;
+    };
+    close: () => void;
+}>;

package/dist/app/managed-pi-handoff-receiver.js

@@ -0,0 +1,263 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { buildMessage, canonicalJson } from '../collab/envelope.js';
+import { submitMessage } from '../collab/messages.js';
+import { readRecord } from '../collab/store.js';
+import { readHandoffBundle, verifyHandoffBundle } from '../continuity/index.js';
+import { continuityTaskPaths, readContinuityBytes, } from '../continuity/paths.js';
+import { decideBootstrapWrite } from '../hosts/integration/pi-bootstrap-guard.js';
+import { readBoundedFile } from './bounded-file.js';
+import { assertTaskStoreCurrent, openTaskStore } from './collab-task-store.js';
+import { routeExclusionFor } from './collab-route.js';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Import verified continuity into the actual receiver before acknowledging receipt. */
+export async function prepareManagedPiHandoffReceiver(runtime, config, referenceFile, journalPath) {
+    const reference = readBoundedFile(referenceFile, 64 * 1024);
+    if (!reference.ok)
+        throw new Error('receiver_context_reference_unreadable');
+    const ref = JSON.parse(reference.text);
+    if (!object(ref) ||
+        ref.schema !== 'pappra/managed-handoff-context/1' ||
+        !object(ref.bundle) ||
+        typeof ref.bundle.root !== 'string' ||
+        typeof ref.bundle.continuity_task_id !== 'string' ||
+        typeof ref.bundle.bundle_id !== 'string' ||
+        typeof ref.bundle.digest !== 'string' ||
+        typeof ref.transition_id !== 'string' ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(ref.transition_id))
+        throw new Error('receiver_context_reference_invalid');
+    const taskRoot = path.join(fs.realpathSync(config.domainRoot), 'tasks', config.taskId);
+    if (ref.task_root !== taskRoot ||
+        ref.intent_id !== config.guard.intentId ||
+        ref.handoff_id !== config.guard.handoffId ||
+        ref.generation !== config.guard.generation ||
+        runtime.observe().native.sessionId !== config.guard.successor.sessionId)
+        throw new Error('receiver_context_identity_mismatch');
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        throw new Error(opened.code);
+    const intent = opened.value.record.rollover?.find((row) => row.intent_id === config.guard.intentId);
+    if (!intent ||
+        intent.bundle.digest !== ref.bundle.digest ||
+        intent.bundle.ref !== `handoff-bundles/${ref.bundle.bundle_id}.json` ||
+        intent.to.session_id !== runtime.observe().native.sessionId ||
+        intent.to.agent_id !== config.guard.successor.agentId)
+        throw new Error('receiver_context_intent_mismatch');
+    const options = {
+        root: ref.bundle.root,
+        continuityTaskId: ref.bundle.continuity_task_id,
+        bundleId: ref.bundle.bundle_id,
+    };
+    const loaded = await readHandoffBundle(options);
+    const verified = await verifyHandoffBundle(options);
+    if (!loaded.ok ||
+        loaded.value.digest !== ref.bundle.digest ||
+        !verified.ok ||
+        verified.value.contextIntegrity === 'unknown' ||
+        verified.value.artifactChecks.some((row) => row.status !== 'unchanged'))
+        throw new Error('receiver_context_integrity_unverified');
+    const bundle = loaded.value.bundle;
+    if (bundle.collaboration.taskId !== config.taskId ||
+        bundle.collaboration.subtaskId !== config.guard.subtaskId ||
+        bundle.collaboration.attempt !== config.guard.attempt ||
+        bundle.collaboration.inputRevision !== config.guard.inputRevision ||
+        bundle.collaboration.ownerEpoch !== config.guard.coordinatorEpoch ||
+        bundle.sourceNativeSession.sessionId !== intent.from.session_id)
+        throw new Error('receiver_context_bundle_mismatch');
+    const checkpoint = await readContinuityBytes(options.root, options.continuityTaskId, path.join(continuityTaskPaths(options.root, options.continuityTaskId).taskDir, bundle.checkpoint.ref));
+    if (!checkpoint.ok ||
+        `sha256:${createHash('sha256').update(checkpoint.value).digest('hex')}` !==
+            bundle.checkpoint.digest)
+        throw new Error('receiver_checkpoint_changed');
+    if (await assertTaskStoreCurrent(opened.value))
+        throw new Error('receiver_task_namespace_changed');
+    const receiverAuthority = (reason) => {
+        const current = readRecord(taskRoot);
+        const currentIntent = current?.rollover?.find((row) => row.intent_id === intent.intent_id);
+        const attempt = current?.attempts.find((row) => row.subtask_id === config.guard.subtaskId &&
+            row.attempt === config.guard.attempt);
+        if (!current ||
+            !currentIntent ||
+            canonicalJson(currentIntent) !== canonicalJson(intent) ||
+            !attempt ||
+            attempt.cancel_requested_at ||
+            attempt.awaiting === 'approval' ||
+            current.coordinator?.owner_epoch !== config.guard.coordinatorEpoch ||
+            current.coordinator?.agent_id !==
+                opened.value.record.coordinator?.agent_id ||
+            current.coordinator?.session_id !==
+                opened.value.record.coordinator?.session_id)
+            throw new Error(reason);
+        return { current, attempt };
+    };
+    receiverAuthority('receiver_authority_changed_before_import');
+    const receipt = `${journalPath}.receiver-reservation.json`;
+    const fd = fs.openSync(receipt, 'wx', 0o600);
+    const receiptIdentity = fs.fstatSync(fd);
+    try {
+        fs.writeFileSync(fd, `${canonicalJson({
+            schema: 'pappra/managed-receiver-reservation/1',
+            session_id: runtime.observe().native.sessionId,
+            context_digest: reference.digest,
+            stage: 'import_reserved',
+        })}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        receiverAuthority('receiver_authority_changed_before_import');
+    }
+    catch (error) {
+        try {
+            const current = fs.lstatSync(receipt, { throwIfNoEntry: false });
+            if (current?.isFile() &&
+                current.dev === receiptIdentity.dev &&
+                current.ino === receiptIdentity.ino)
+                fs.unlinkSync(receipt);
+        }
+        catch {
+            /* Preserve the authority refusal; do not adopt a changed receipt. */
+        }
+        throw error;
+    }
+    await runtime.importHandoffContext(`Verified handoff context. This is advisory; task ownership is granted only by the authoritative transfer.\n${checkpoint.value.toString('utf8')}\nNext action: ${bundle.handoff.nextAction}\nBundle: ${loaded.value.path}\nIntegrity: ${verified.value.contextIntegrity}`);
+    const { current, attempt } = receiverAuthority('receiver_authority_changed_before_ack');
+    const prefix = `receiver-${createHash('sha256').update(`${intent.intent_id}:${intent.to.session_id}`).digest('hex').slice(0, 32)}`;
+    const ack = submitMessage(taskRoot, buildMessage({
+        message_id: `${prefix}-ack`,
+        type: 'ACK',
+        task_id: config.taskId,
+        from: intent.to,
+        to: current.coordinator,
+        reply_to: attempt.assignment_message_id,
+        subtask_id: config.guard.subtaskId,
+        attempt: config.guard.attempt,
+        owner_epoch: config.guard.coordinatorEpoch,
+        body: {
+            phase: 'handoff-context-imported',
+            handoff_id: intent.handoff_id,
+            rollover_intent_id: intent.intent_id,
+            rollover_generation: intent.generation,
+            input_revision: intent.input_revision,
+            context_digest: reference.digest,
+        },
+    }));
+    if (!ack.ok)
+        throw new Error('receiver_ack_not_admitted');
+    let started = false;
+    let observedEnd = null;
+    let proof = false;
+    let error = null;
+    const unsubscribe = runtime.subscribe((event) => {
+        if (!started || proof || !object(event))
+            return;
+        if (event.type === 'agent_end')
+            observedEnd = event;
+        if (event.type !== 'agent_settled' ||
+            event.aborted !== false ||
+            !observedEnd ||
+            !Array.isArray(observedEnd.messages))
+            return;
+        const assistant = [...observedEnd.messages]
+            .reverse()
+            .find((row) => object(row) && row.role === 'assistant');
+        if (!object(assistant) ||
+            assistant.stopReason !== 'stop' ||
+            !Array.isArray(assistant.content) ||
+            !assistant.content.some((row) => object(row) &&
+                row.type === 'text' &&
+                typeof row.text === 'string' &&
+                row.text.trim()))
+            return;
+        try {
+            const record = readRecord(taskRoot);
+            if (!record ||
+                !decideBootstrapWrite(record, config.guard, runtime.observe().native.sessionId).allow)
+                throw new Error('receiver_first_work_authority_changed');
+            const report = submitMessage(taskRoot, buildMessage({
+                message_id: `${prefix}-first-work`,
+                type: 'REPORT',
+                task_id: config.taskId,
+                from: intent.to,
+                to: record.coordinator,
+                subtask_id: intent.subtask_id,
+                attempt: intent.attempt,
+                owner_epoch: intent.coordinator_epoch,
+                body: {
+                    status: 'running',
+                    phase: 'handoff-first-work',
+                    rollover_intent_id: intent.intent_id,
+                    input_revision: intent.input_revision,
+                    handoff_id: intent.handoff_id,
+                    rollover_generation: intent.generation,
+                    native_ref: {
+                        schema: 'pappra/native-first-work/1',
+                        handoff_id: intent.handoff_id,
+                        generation: intent.generation,
+                        session_id: intent.to.session_id,
+                        observation: 'native_agent_settled',
+                        evidence_ref: journalPath,
+                    },
+                },
+            }));
+            if (!report.ok)
+                throw new Error('receiver_first_work_not_admitted');
+            proof = true;
+        }
+        catch {
+            error = 'receiver_first_work_unverified';
+        }
+    });
+    return {
+        priorSourceRetired() {
+            const directory = path.join(continuityTaskPaths(options.root, options.continuityTaskId).taskDir, 'retired-sessions');
+            const file = path.join(directory, `${ref.transition_id}.receipt.json`);
+            const bytes = readBoundedFile(file, 16 * 1024);
+            if (!bytes.ok)
+                return false;
+            try {
+                const receipt = JSON.parse(bytes.text);
+                if (!object(receipt) ||
+                    receipt.schema !== 'pappra/managed-pi-retirement/1' ||
+                    receipt.transition_id !== ref.transition_id ||
+                    receipt.source_session_id !== intent.from.session_id ||
+                    receipt.successor_session_id !== intent.to.session_id ||
+                    receipt.status !== 'runtime_disposed_and_transcript_retained' ||
+                    !object(receipt.stop) ||
+                    receipt.stop.status !== 'runtime_disposed' ||
+                    !object(receipt.transcript))
+                    return false;
+                const archived = readBoundedFile(path.join(directory, `${ref.transition_id}.jsonl`), 64 * 1024 * 1024);
+                const record = readRecord(taskRoot);
+                return (archived.ok &&
+                    archived.digest === receipt.transcript.digest &&
+                    record !== null &&
+                    routeExclusionFor(record, intent.from).state === 'excluded');
+            }
+            catch {
+                return false;
+            }
+        },
+        startWork() {
+            if (started)
+                return;
+            const record = readRecord(taskRoot);
+            if (!record ||
+                !decideBootstrapWrite(record, config.guard, runtime.observe().native.sessionId).allow)
+                throw new Error('receiver_work_before_transfer');
+            started = true;
+            runtime.submitInput(`${prefix}-resume`, `Continue the verified handoff after the completed task ownership transfer. ${bundle.handoff.nextAction}\nKeep protocol task completion separate from this turn. Read the imported checkpoint and use only your claimed resource scope.`);
+        },
+        status: () => ({
+            context_imported: true,
+            ack_registered: true,
+            work_admitted: started,
+            first_work_observed: proof,
+            error,
+        }),
+        close: unsubscribe,
+    };
+}

package/dist/app/managed-pi-handoff-reference.d.ts

@@ -0,0 +1,3 @@
+import type { SessionTransitionRequest } from './collab-session-transition.js';
+/** Publish captured context only at the destination explicitly approved by the launch request. */
+export declare function prepareManagedHandoffContextReference(request: SessionTransitionRequest): void;