yaver-feedback-react-native 0.9.2 → 0.9.4

package/README.md

@@ -60,7 +60,7 @@ Starting with **0.6.0**, the SDK login screen mirrors the Yaver mobile app: nati
 Drop in `<FeedbackModal />` and the first time a user triggers feedback without a cached session, they get:
 
 1. A full-screen login modal — Apple (native) / Google / GitHub / GitLab / Microsoft (in-app browser) / email + password (inline).
-2. A picker of the machines they can reach — **their own dev boxes** plus **guest-shared machines** (where another user invited them).
+2. A picker of the authenticated account's own dev boxes.
 
 Both screens persist their selection to `AsyncStorage`, so subsequent launches reconnect silently.
 
@@ -89,6 +89,107 @@ function App() {
 
 Shake your phone to open the feedback modal. On mobile the quick-access icon stays hidden until that first shake, then remains tappable for the rest of the session unless the user hides it. For launch, the sheet exposes three actions only: hot reload, vibing, and screenshot & fix.
 
+### Account-scoped Dogfood mode
+
+An app can send only explicitly approved app accounts directly into Vibing,
+while everyone else keeps the normal Feedback sheet:
+
+```tsx
+YaverFeedback.init({
+  dogfood: {
+    enabled: true,
+    currentAccountId: session.user.id,
+    accountIds: ['approved-app-account-id'],
+    label: 'My App',
+    onExit: () => setDogfoodPreference(false),
+  },
+});
+```
+
+The match is exact and fails closed when the current account is absent. The
+small `Y` identifies Dogfood mode; tapping it offers a confirmed exit back to
+Feedback mode. This allowlist controls SDK presentation only—tasks and reloads
+still require the user's normal Yaver authentication.
+
+### Device-enrolled Dogfood for apps without their own OAuth/backend
+
+Mount `FeedbackModal`, then call the reusable wizard from the host app's
+Settings button:
+
+```tsx
+YaverFeedback.beginDogfoodOnboarding({
+  appId: 'io.example.app',
+  label: 'Example',
+  projectName: 'example',
+  framework: 'expo',
+});
+```
+
+The wizard runs Yaver OAuth first, then machine, coding runner/model, project,
+and Browser/Hermes/WebRTC selection. It renders raw build logs and exposes the
+ready preview. The app also creates a random installation ID and an Ed25519 key
+inside SecureStore. The ID is a public handle, not a credential: enrollment
+and each short session require a server challenge signed by the private key.
+An owner approves, cancels, or revokes the installation from Yaver Settings or
+MCP. Re-registering rotates the key/ID, preserves only the logical local slot,
+and supersedes that slot's prior active generation without disabling another
+phone.
+
+Install `expo-secure-store` and `expo-crypto` in Expo hosts. Bare React Native
+hosts may provide a `secureStore` implementation. Runtime/build controls still
+require full Yaver OAuth; the account-free installation token defaults to
+`feedback` + `blackbox` and cannot be rotated into a long-lived owner token.
+
+### Embeddable Dogfood runtime
+
+App owners can also embed the actual source → dev-server → render lifecycle.
+`DogfoodController` is deliberately headless: constructing it does nothing;
+your own button calls `trigger()`, your preview renders `result.url`, and your
+console renders `snapshot.logs`. Retry and partial-session cleanup are handled
+by the controller.
+
+```tsx
+import {
+  DogfoodController,
+  P2PClient,
+  createP2PDogfoodDriver,
+} from 'yaver-feedback-react-native';
+
+const client = new P2PClient(agentUrl, signedInUserToken);
+const dogfood = new DogfoodController(
+  {
+    name: 'My App',
+    workDir: '/workspace/my-app',
+    framework: 'expo',       // also react-native, flutter, vite, next
+    lane: 'browser',         // Hermes is Expo/RN only; Flutter uses browser/WebRTC
+  },
+  createP2PDogfoodDriver(client),
+  {
+    onChange(snapshot) {
+      setPhase(snapshot.phase);
+      setConsoleText(snapshot.logs.map((line) => line.text).join('\n'));
+    },
+  },
+);
+
+// Explicit user intent: call only from your Dogfood button.
+const onDogfoodPress = () => dogfood.trigger().then(({ url }) => setPreviewUrl(url));
+const onRetryPress = () => dogfood.retry();
+const onLeaveScreen = () => dogfood.stop();
+```
+
+The default P2P driver calls the same `/dev/start`, `/dev/status`, `/dev/stop`,
+and `/dev/events` endpoints as Yaver's Projects browser lane. Package-manager
+and compiler output—including `$ npm install`, Expo/Metro, and Flutter web
+output—arrives uncollapsed in `snapshot.logs`. Starting tools requires the
+normal signed-in Yaver user token; a narrow feedback-only SDK token cannot
+spawn processes.
+
+For Yaver itself, installing `yaver-cli` supplies these agent endpoints. The
+native Yaver app checks the selected box for a real Yaver checkout and offers
+`Clone Yaver source` when it is absent; cloning still occurs only after that
+explicit tap.
+
 ### Quick Icon Styling
 
 The quick icon is configurable at compile time through `YaverFeedback.init(...)`, with render-time overrides still available through `<QuickActionIcon />` props when needed. If you do nothing, the SDK uses a high-visibility orange bubble by default so it stays distinct from the blue/indigo FAB styling many mobile apps already have.

package/dist/AuthOverlay.d.ts

@@ -1,16 +1,3 @@
 import React from 'react';
-/**
- * Presentation layer for the SDK's auth + machine-picker modals.
- *
- * Mounts automatically inside `<FeedbackModal />`, so consumers of the SDK
- * get in-app login with no extra wiring. It listens for events emitted by
- * `YaverFeedback.showLogin()` / `showMachinePicker()`:
- *
- *   yaverFeedback:startLogin          → show login modal
- *   yaverFeedback:startMachinePicker  → show machine picker
- *
- * The overlay closes itself once login/pick succeeds, then re-emits
- * `yaverFeedback:startReport` so the user continues straight into the
- * feedback flow they originally triggered.
- */
+/** Owner sign-in and owner-machine selection for the Feedback SDK. */
 export declare const AuthOverlay: React.FC;

package/dist/AuthOverlay.js

@@ -38,74 +38,47 @@ const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const LoginScreen_1 = require("./LoginScreen");
 const MachinePickerScreen_1 = require("./MachinePickerScreen");
-const GuestOnboardingScreen_1 = require("./GuestOnboardingScreen");
 const YaverFeedback_1 = require("./YaverFeedback");
 const auth_1 = require("./auth");
-/**
- * Presentation layer for the SDK's auth + machine-picker modals.
- *
- * Mounts automatically inside `<FeedbackModal />`, so consumers of the SDK
- * get in-app login with no extra wiring. It listens for events emitted by
- * `YaverFeedback.showLogin()` / `showMachinePicker()`:
- *
- *   yaverFeedback:startLogin          → show login modal
- *   yaverFeedback:startMachinePicker  → show machine picker
- *
- * The overlay closes itself once login/pick succeeds, then re-emits
- * `yaverFeedback:startReport` so the user continues straight into the
- * feedback flow they originally triggered.
- */
+/** Owner sign-in and owner-machine selection for the Feedback SDK. */
 const AuthOverlay = () => {
     const [loginVisible, setLoginVisible] = (0, react_1.useState)(false);
-    const [guestVisible, setGuestVisible] = (0, react_1.useState)(false);
     const [pickerVisible, setPickerVisible] = (0, react_1.useState)(false);
     const [token, setToken] = (0, react_1.useState)(null);
-    const [pendingInviteCode, setPendingInviteCode] = (0, react_1.useState)(null);
     const activeOverlayRef = (0, react_1.useRef)('none');
     const openLogin = (0, react_1.useCallback)(() => {
         activeOverlayRef.current = 'login';
-        setGuestVisible(false);
         setPickerVisible(false);
         setLoginVisible(true);
     }, []);
-    const openGuest = (0, react_1.useCallback)(() => {
-        activeOverlayRef.current = 'guest';
-        setLoginVisible(false);
-        setPickerVisible(false);
-        setGuestVisible(true);
-    }, []);
     const openPicker = (0, react_1.useCallback)(() => {
         activeOverlayRef.current = 'picker';
         setLoginVisible(false);
-        setGuestVisible(false);
         setPickerVisible(true);
     }, []);
     const closeAll = (0, react_1.useCallback)(() => {
         activeOverlayRef.current = 'none';
         setLoginVisible(false);
-        setGuestVisible(false);
         setPickerVisible(false);
     }, []);
     (0, react_1.useEffect)(() => {
         let mounted = true;
-        (async () => {
-            const cached = await (0, auth_1.getToken)();
+        void (0, auth_1.getToken)().then((cached) => {
             if (mounted && cached)
                 setToken(cached);
-        })();
+        });
         const loginSub = react_native_1.DeviceEventEmitter.addListener('yaverFeedback:startLogin', () => {
-            if (activeOverlayRef.current !== 'none')
-                return;
-            openLogin();
+            if (activeOverlayRef.current === 'none')
+                openLogin();
         });
         const pickerSub = react_native_1.DeviceEventEmitter.addListener('yaverFeedback:startMachinePicker', async () => {
             if (activeOverlayRef.current !== 'none')
                 return;
             const cached = await (0, auth_1.getToken)();
-            if (cached)
+            if (cached) {
                 setToken(cached);
-            if (cached)
                 openPicker();
+            }
         });
         return () => {
             mounted = false;
@@ -113,49 +86,23 @@ const AuthOverlay = () => {
             pickerSub.remove();
         };
     }, [openLogin, openPicker]);
-    const continueAfterAuth = async (newToken, inviteCode) => {
+    const handleLoggedIn = async (newToken) => {
         setToken(newToken);
         await YaverFeedback_1.YaverFeedback.setAuthToken(newToken);
-        const devices = await (0, auth_1.listReachableDevices)(newToken).catch(() => ({ owned: [], shared: [] }));
-        const cleanedInviteCode = (inviteCode ?? '').trim().toUpperCase();
-        if (cleanedInviteCode) {
-            setPendingInviteCode(cleanedInviteCode);
-            openGuest();
-            return;
-        }
-        if (devices.owned.length === 0 && devices.shared.length === 0) {
-            openGuest();
-            return;
-        }
         openPicker();
     };
-    const handleLoggedIn = async (newToken, opts) => {
-        await continueAfterAuth(newToken, opts?.inviteCode);
-    };
     const handleDevicePicked = async (device) => {
         await YaverFeedback_1.YaverFeedback.setPreferredDevice(device.deviceId);
         closeAll();
-        // Continue straight into the feedback flow the user originally triggered.
         react_native_1.DeviceEventEmitter.emit('yaverFeedback:startReport');
     };
     return (<>
       <react_native_1.Modal visible={loginVisible} animationType="slide" presentationStyle="fullScreen" onRequestClose={closeAll}>
-        <LoginScreen_1.YaverLoginScreen onLoggedIn={handleLoggedIn} onCancel={closeAll} initialInviteCode={pendingInviteCode ?? YaverFeedback_1.YaverFeedback.getConfig()?.guestInviteCode}/>
+        <LoginScreen_1.YaverLoginScreen onLoggedIn={handleLoggedIn} onCancel={closeAll}/>
       </react_native_1.Modal>
-
       <react_native_1.Modal visible={pickerVisible && !!token} animationType="slide" presentationStyle="fullScreen" onRequestClose={closeAll}>
         {token && (<MachinePickerScreen_1.YaverMachinePickerScreen token={token} currentDeviceId={YaverFeedback_1.YaverFeedback.getConfig()?.preferredDeviceId} onPick={handleDevicePicked} onCancel={closeAll}/>)}
       </react_native_1.Modal>
-
-      <react_native_1.Modal visible={guestVisible && !!token} animationType="slide" presentationStyle="fullScreen" onRequestClose={closeAll}>
-        {token && (<GuestOnboardingScreen_1.YaverGuestOnboardingScreen token={token} initialInviteCode={pendingInviteCode ?? YaverFeedback_1.YaverFeedback.getConfig()?.guestInviteCode} onContinue={() => {
-                setPendingInviteCode(null);
-                openPicker();
-            }} onCancel={() => {
-                setPendingInviteCode(null);
-                openPicker();
-            }}/>)}
-      </react_native_1.Modal>
     </>);
 };
 exports.AuthOverlay = AuthOverlay;

package/dist/Discovery.js

@@ -179,12 +179,6 @@ class YaverDiscovery {
                 needsAuth: !!d.needsAuth,
                 runnerDown: !!d.runnerDown,
                 lastHeartbeat: d.lastHeartbeat ?? 0,
-                isGuest: !!d.isGuest,
-                hostUserId: d.hostUserId,
-                hostName: d.hostName,
-                hostEmail: d.hostEmail,
-                hostUserIdString: d.hostUserIdString,
-                accessScope: d.accessScope ?? 'owner',
                 quicHost: d.quicHost ?? d.host ?? '',
                 quicPort: d.quicPort ?? 0,
                 httpPort: d.httpPort ?? d.quicPort,

package/dist/DogfoodRuntime.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Embeddable Dogfood orchestration for React Native hosts.
+ *
+ * The SDK deliberately does not own the host's button, WebView, navigation, or
+ * Yaver transport. It owns the failure-prone lifecycle underneath them:
+ * explicit trigger -> prepare -> start -> ready, bounded log retention,
+ * generation-safe Retry, and deterministic cleanup of partial sessions.
+ *
+ * Yaver mobile uses this class for Yaver-on-Yaver. Third-party apps use the
+ * same class with their own project descriptor and a driver backed by
+ * P2PClient (or another authenticated Yaver transport).
+ */
+export type DogfoodLane = 'browser' | 'hermes' | 'webrtc';
+export type DogfoodPhase = 'idle' | 'preparing' | 'starting' | 'compiling' | 'ready' | 'failed' | 'stopping' | 'stopped';
+export interface DogfoodProject {
+    name: string;
+    workDir: string;
+    framework: string;
+    lane: DogfoodLane;
+    /** Optional source URL for drivers that can clone missing source. */
+    repositoryUrl?: string;
+    /** Optional native target from /remote-runtime/capabilities for WebRTC. */
+    nativeTargetId?: string;
+}
+export interface DogfoodLaneOption {
+    lane: DogfoodLane;
+    label: string;
+    supported: boolean;
+    default: boolean;
+    reason?: string;
+}
+/** One framework-to-lane matrix for Yaver and third-party consumers. */
+export declare function dogfoodLaneOptions(framework: string, capabilities?: {
+    nativeRuntimeAvailable?: boolean;
+    selfDevelopment?: boolean;
+}): DogfoodLaneOption[];
+export declare function defaultDogfoodLane(framework: string): DogfoodLane;
+export interface DogfoodLogLine {
+    text: string;
+    at: number;
+    stream?: 'stdout' | 'stderr' | 'system';
+}
+export interface DogfoodFailure {
+    code: string;
+    error: string;
+    remedy: string;
+    retryable: boolean;
+    fixPrompt?: string;
+}
+export interface DogfoodResult {
+    lane: DogfoodLane;
+    url?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DogfoodSnapshot {
+    phase: DogfoodPhase;
+    attempt: number;
+    project: DogfoodProject;
+    message: string;
+    logs: readonly DogfoodLogLine[];
+    startedAt?: number;
+    lastOutputAt?: number;
+    result?: DogfoodResult;
+    failure?: DogfoodFailure;
+}
+export interface DogfoodRunContext {
+    project: DogfoodProject;
+    attempt: number;
+    /** Raw package-manager/compiler output. ANSI is intentionally preserved. */
+    log(line: string | DogfoodLogLine): void;
+    setPhase(phase: Extract<DogfoodPhase, 'preparing' | 'starting' | 'compiling'>, message: string): void;
+    /**
+     * Register cleanup immediately after acquiring a resource.
+     *
+     * `session` cleanups run on failure/stop. `transient` cleanups also run when
+     * ownership is handed to another screen (normally an SSE subscription).
+     */
+    registerCleanup(cleanup: () => void | Promise<void>, scope?: 'session' | 'transient'): void;
+    isCurrent(): boolean;
+}
+export interface DogfoodDriver {
+    prepare?(context: DogfoodRunContext): Promise<void>;
+    start(context: DogfoodRunContext): Promise<DogfoodResult>;
+}
+export interface DogfoodControllerOptions {
+    maxLogLines?: number;
+    onChange?: (snapshot: DogfoodSnapshot) => void;
+}
+export declare class DogfoodRuntimeError extends Error {
+    readonly failure: DogfoodFailure;
+    constructor(failure: DogfoodFailure);
+}
+export declare function validateDogfoodProject(project: DogfoodProject): DogfoodFailure | null;
+/** Convert one /dev/events frame into console lines without hiding raw output. */
+export declare function runtimeLogLinesFromDevEvent(event: any): string[];
+/** Backwards-friendly name for consumers that discovered this via Dogfood. */
+export declare const dogfoodLogLinesFromDevEvent: typeof runtimeLogLinesFromDevEvent;
+export declare class DogfoodController {
+    readonly project: DogfoodProject;
+    private readonly driver;
+    private generation;
+    private cleanups;
+    private runPromise;
+    private readonly maxLogLines;
+    private readonly onChange?;
+    private state;
+    constructor(project: DogfoodProject, driver: DogfoodDriver, options?: DogfoodControllerOptions);
+    snapshot(): DogfoodSnapshot;
+    /** Nothing starts until the host calls this method from its explicit action. */
+    trigger(): Promise<DogfoodResult>;
+    retry(): Promise<DogfoodResult>;
+    private run;
+    /** Stop the active/partial run and release every resource. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Transfer the live session to a host-owned preview screen. Stream/timer
+     * cleanups run; session cleanup is discarded because the receiving screen
+     * now owns it.
+     */
+    handoff(): Promise<DogfoodResult | undefined>;
+    private runCleanups;
+    private replace;
+}

package/dist/DogfoodRuntime.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * Embeddable Dogfood orchestration for React Native hosts.
+ *
+ * The SDK deliberately does not own the host's button, WebView, navigation, or
+ * Yaver transport. It owns the failure-prone lifecycle underneath them:
+ * explicit trigger -> prepare -> start -> ready, bounded log retention,
+ * generation-safe Retry, and deterministic cleanup of partial sessions.
+ *
+ * Yaver mobile uses this class for Yaver-on-Yaver. Third-party apps use the
+ * same class with their own project descriptor and a driver backed by
+ * P2PClient (or another authenticated Yaver transport).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DogfoodController = exports.dogfoodLogLinesFromDevEvent = exports.DogfoodRuntimeError = void 0;
+exports.dogfoodLaneOptions = dogfoodLaneOptions;
+exports.defaultDogfoodLane = defaultDogfoodLane;
+exports.validateDogfoodProject = validateDogfoodProject;
+exports.runtimeLogLinesFromDevEvent = runtimeLogLinesFromDevEvent;
+/** One framework-to-lane matrix for Yaver and third-party consumers. */
+function dogfoodLaneOptions(framework, capabilities = {}) {
+    const normalized = String(framework || '').trim().toLowerCase();
+    const reactNative = normalized === 'expo' || normalized === 'react-native';
+    const browserCapable = reactNative || [
+        'flutter', 'web', 'next', 'nextjs', 'vite', 'remix', 'svelte', 'vue', 'angular',
+    ].includes(normalized);
+    const nativeAvailable = capabilities.nativeRuntimeAvailable === true;
+    const hermesReason = reactNative
+        ? undefined
+        : 'Hermes is available only for Expo and React Native projects.';
+    const browserReason = browserCapable
+        ? undefined
+        : 'The browser lane is available for browser-capable projects such as React Native, Expo, Flutter, and web apps.';
+    return [
+        { lane: 'browser', label: 'Browser lane', supported: browserCapable, default: browserCapable, reason: browserReason },
+        { lane: 'hermes', label: 'Hermes', supported: !hermesReason, default: false, reason: hermesReason },
+        {
+            lane: 'webrtc', label: 'WebRTC native', supported: nativeAvailable, default: false,
+            reason: nativeAvailable ? undefined : 'No native simulator, emulator, or device runtime is available on this machine.',
+        },
+    ];
+}
+function defaultDogfoodLane(framework) {
+    return dogfoodLaneOptions(framework).find((option) => option.default && option.supported)?.lane || 'browser';
+}
+class DogfoodRuntimeError extends Error {
+    constructor(failure) {
+        super(failure.error);
+        this.name = 'DogfoodRuntimeError';
+        this.failure = failure;
+    }
+}
+exports.DogfoodRuntimeError = DogfoodRuntimeError;
+function validateDogfoodProject(project) {
+    const framework = String(project.framework || '').trim().toLowerCase();
+    if (!String(project.workDir || '').trim()) {
+        return {
+            code: 'DOGFOOD_PROJECT_PATH_REQUIRED',
+            error: 'Dogfood needs the project directory on the selected machine.',
+            remedy: 'Choose or clone the project source, then trigger Dogfood again.',
+            retryable: false,
+        };
+    }
+    if (project.lane === 'hermes' && framework !== 'expo' && framework !== 'react-native') {
+        return {
+            code: 'DOGFOOD_HERMES_FRAMEWORK_UNSUPPORTED',
+            error: `Hermes cannot run a ${framework || 'non-React-Native'} project.`,
+            remedy: framework === 'flutter'
+                ? 'Use the browser lane (Flutter web) or WebRTC for a native Flutter runtime.'
+                : 'Use the browser or WebRTC lane, or select an Expo/React Native project.',
+            retryable: false,
+        };
+    }
+    return null;
+}
+/** Convert one /dev/events frame into console lines without hiding raw output. */
+function runtimeLogLinesFromDevEvent(event) {
+    if (!event || typeof event !== 'object')
+        return [];
+    if (event.type === 'log' && typeof event.logLine === 'string') {
+        return event.logLine.trimEnd() ? [event.logLine.trimEnd()] : [];
+    }
+    if (event.type === 'snapshot' && Array.isArray(event.snapshot?.recentLogs)) {
+        return event.snapshot.recentLogs
+            .map((line) => String(line).trimEnd())
+            .filter(Boolean);
+    }
+    if (event.type === 'progress' || event.type === 'phase') {
+        const phase = typeof event.phase === 'string' ? event.phase.replace(/_/g, ' ') : 'working';
+        const pct = typeof event.pct === 'number' ? ` ${Math.round(event.pct)}%` : '';
+        const file = typeof event.currentFile === 'string' && event.currentFile
+            ? ` · ${String(event.currentFile).split('/').slice(-2).join('/')}`
+            : '';
+        return [`${phase}${pct}${file}`.trim()];
+    }
+    if (event.type === 'error') {
+        return String(event.message || 'Dev server failed')
+            .split('\n')
+            .map((line) => line.trimEnd())
+            .filter(Boolean);
+    }
+    if (typeof event.message === 'string' && event.message.trim() &&
+        ['starting', 'building', 'phase', 'ready', 'reload', 'stopped'].includes(String(event.type))) {
+        return [event.message.trimEnd()];
+    }
+    return [];
+}
+/** Backwards-friendly name for consumers that discovered this via Dogfood. */
+exports.dogfoodLogLinesFromDevEvent = runtimeLogLinesFromDevEvent;
+function failureFrom(error) {
+    if (error instanceof DogfoodRuntimeError)
+        return error.failure;
+    const candidate = error;
+    return {
+        code: typeof candidate?.code === 'string' ? candidate.code : 'DOGFOOD_START_FAILED',
+        error: error instanceof Error ? error.message : String(error || 'Dogfood could not start.'),
+        remedy: typeof candidate?.remedy === 'string'
+            ? candidate.remedy
+            : 'Fix the named project or runtime failure, then retry Dogfood.',
+        retryable: candidate?.retryable !== false,
+        fixPrompt: typeof candidate?.fixPrompt === 'string' ? candidate.fixPrompt : undefined,
+    };
+}
+class DogfoodController {
+    constructor(project, driver, options = {}) {
+        this.generation = 0;
+        // Cleanup ownership is per attempt. An old async attempt may finish after
+        // Stop + Retry has already acquired a new runtime; a shared list lets that
+        // obsolete attempt tear down the newer session. Generation-keyed ownership
+        // makes that race impossible while keeping Stop able to release everything.
+        this.cleanups = new Map();
+        this.runPromise = null;
+        this.project = project;
+        this.driver = driver;
+        this.maxLogLines = Math.max(20, options.maxLogLines ?? 200);
+        this.onChange = options.onChange;
+        this.state = { phase: 'idle', attempt: 0, project, message: 'Ready to dogfood', logs: [] };
+    }
+    snapshot() {
+        return { ...this.state, logs: [...this.state.logs] };
+    }
+    /** Nothing starts until the host calls this method from its explicit action. */
+    trigger() {
+        if (this.runPromise)
+            return this.runPromise;
+        const promise = this.run();
+        this.runPromise = promise;
+        void promise.finally(() => {
+            if (this.runPromise === promise)
+                this.runPromise = null;
+        }).catch(() => { });
+        return promise;
+    }
+    retry() {
+        return this.trigger();
+    }
+    async run() {
+        const generation = ++this.generation;
+        const attempt = this.state.attempt + 1;
+        await this.runCleanups('all');
+        const invalid = validateDogfoodProject(this.project);
+        if (invalid) {
+            this.replace({ phase: 'failed', attempt, project: this.project, message: invalid.error, logs: [], failure: invalid });
+            throw new DogfoodRuntimeError(invalid);
+        }
+        this.replace({
+            phase: 'preparing', attempt, project: this.project,
+            message: `Preparing ${this.project.name}…`, logs: [], startedAt: Date.now(),
+        });
+        const context = {
+            project: this.project,
+            attempt,
+            log: (line) => {
+                if (generation !== this.generation)
+                    return;
+                const entry = typeof line === 'string'
+                    ? { text: line, at: Date.now(), stream: 'stdout' }
+                    : { ...line, at: line.at || Date.now() };
+                if (!entry.text.trim())
+                    return;
+                const logs = [...this.state.logs, entry].slice(-this.maxLogLines);
+                this.replace({ ...this.state, logs, lastOutputAt: entry.at });
+            },
+            setPhase: (phase, message) => {
+                if (generation === this.generation)
+                    this.replace({ ...this.state, phase, message });
+            },
+            registerCleanup: (cleanup, scope = 'session') => {
+                if (generation !== this.generation) {
+                    void Promise.resolve(cleanup()).catch(() => { });
+                    return;
+                }
+                const owned = this.cleanups.get(generation) || [];
+                owned.push({ fn: cleanup, scope });
+                this.cleanups.set(generation, owned);
+            },
+            isCurrent: () => generation === this.generation,
+        };
+        try {
+            await this.driver.prepare?.(context);
+            if (!context.isCurrent())
+                throw new DogfoodRuntimeError({
+                    code: 'DOGFOOD_ATTEMPT_REPLACED', error: 'A newer Dogfood attempt replaced this one.',
+                    remedy: 'Wait for the newer attempt.', retryable: true,
+                });
+            context.setPhase('starting', `Starting ${this.project.name} on the ${this.project.lane} lane…`);
+            const result = await this.driver.start(context);
+            if (!context.isCurrent()) {
+                await this.runCleanups('all', generation);
+                throw new DogfoodRuntimeError({
+                    code: 'DOGFOOD_ATTEMPT_REPLACED', error: 'A newer Dogfood attempt replaced this one.',
+                    remedy: 'Wait for the newer attempt.', retryable: true,
+                });
+            }
+            this.replace({ ...this.state, phase: 'ready', message: `${this.project.name} is ready`, result, failure: undefined });
+            return result;
+        }
+        catch (error) {
+            const failure = failureFrom(error);
+            await this.runCleanups('all', generation);
+            if (generation === this.generation) {
+                this.replace({ ...this.state, phase: 'failed', message: failure.error, failure, result: undefined });
+            }
+            throw error instanceof DogfoodRuntimeError ? error : new DogfoodRuntimeError(failure);
+        }
+    }
+    /** Stop the active/partial run and release every resource. Idempotent. */
+    async stop() {
+        ++this.generation;
+        this.runPromise = null;
+        this.replace({ ...this.state, phase: 'stopping', message: `Stopping ${this.project.name}…` });
+        await this.runCleanups('all');
+        this.replace({ ...this.state, phase: 'stopped', message: `${this.project.name} stopped`, result: undefined });
+    }
+    /**
+     * Transfer the live session to a host-owned preview screen. Stream/timer
+     * cleanups run; session cleanup is discarded because the receiving screen
+     * now owns it.
+     */
+    async handoff() {
+        if (this.state.phase !== 'ready')
+            return undefined;
+        await this.runCleanups('transient', this.generation);
+        // The receiving screen now owns the live session. Forget its session
+        // cleanup without touching cleanups belonging to any other generation.
+        this.cleanups.delete(this.generation);
+        return this.state.result;
+    }
+    async runCleanups(which, generation) {
+        const generations = generation === undefined ? [...this.cleanups.keys()] : [generation];
+        const selected = [];
+        for (const key of generations) {
+            const owned = this.cleanups.get(key) || [];
+            selected.push(...(which === 'all' ? owned : owned.filter((item) => item.scope === 'transient')));
+            const retained = which === 'all' ? [] : owned.filter((item) => item.scope !== 'transient');
+            if (retained.length)
+                this.cleanups.set(key, retained);
+            else
+                this.cleanups.delete(key);
+        }
+        for (const cleanup of selected.reverse()) {
+            try {
+                await cleanup.fn();
+            }
+            catch { /* cleanup is best-effort but never skipped */ }
+        }
+    }
+    replace(next) {
+        this.state = next;
+        this.onChange?.(this.snapshot());
+    }
+}
+exports.DogfoodController = DogfoodController;