@portel/photon 1.7.0 → 1.8.1

package/dist/daemon/protocol.d.ts

@@ -16,6 +16,8 @@ export interface DaemonRequest {
     photonPath?: string;
     sessionId?: string;
     clientType?: 'cli' | 'mcp' | 'code-mode' | 'beam';
+    /** Instance name hint for auto-recovery from session drift */
+    instanceName?: string;
     method?: string;
     args?: Record<string, unknown>;
     /** Response to a prompt request */
@@ -32,7 +34,7 @@ export interface DaemonRequest {
     jobId?: string;
     /** Cron expression for scheduled jobs */
     cron?: string;
-    /** Last event ID received by client (for replay on reconnect) */
+    /** Last event timestamp received by client (for delta sync on reconnect) */
     lastEventId?: string;
 }
 /**
@@ -44,6 +46,8 @@ export interface DaemonResponse {
     success?: boolean;
     data?: unknown;
     error?: string;
+    /** Actionable hint for the caller when type === 'error' */
+    suggestion?: string;
     /** Prompt request details (when type === 'prompt') */
     prompt?: {
         type: 'text' | 'password' | 'confirm' | 'select';
@@ -58,7 +62,7 @@ export interface DaemonResponse {
     channel?: string;
     /** Message payload for channel_message type */
     message?: unknown;
-    /** Event ID for tracking (for replay support) */
+    /** Event timestamp for tracking (for delta sync support) */
     eventId?: string;
 }
 /**
@@ -78,6 +82,7 @@ export interface DaemonStatus {
 export interface PhotonSession {
     id: string;
     instance: PhotonMCPClass;
+    instanceName: string;
     createdAt: number;
     lastActivity: number;
     clientType?: string;

package/dist/daemon/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/daemon/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EACA,SAAS,GACT,MAAM,GACN,UAAU,GACV,QAAQ,GACR,iBAAiB,GACjB,WAAW,GACX,aAAa,GACb,SAAS,GACT,MAAM,GACN,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,kBAAkB,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACtC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QACjD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC5D,CAAC;IACF,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAyDvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAazE"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/daemon/protocol.ts"],"names":[],"mappings":"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"}

package/dist/daemon/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/daemon/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2HH;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,GAAG,GAAG,GAA6B,CAAC;IAE1C,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE7C,MAAM,UAAU,GAAG;QACjB,SAAS;QACT,MAAM;QACN,UAAU;QACV,QAAQ;QACR,iBAAiB;QACjB,WAAW;QACX,aAAa;QACb,SAAS;QACT,MAAM;QACN,QAAQ;QACR,UAAU;QACV,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,kBAAkB;KACnB,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3D,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACnD,CAAC;IAED,4CAA4C;IAC5C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC,EAAE,CAAC;QACzE,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACpD,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IAED,sDAAsD;IACtD,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC5B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACjD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACjD,CAAC;IAED,4BAA4B;IAC5B,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IAClD,CAAC;IAED,6BAA6B;IAC7B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACvD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,GAAG,GAAG,GAA8B,CAAC;IAE3C,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7C,IACE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAClF,GAAG,CAAC,IAAc,CACnB;QAED,OAAO,KAAK,CAAC;IAEf,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/daemon/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgIH;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,GAAG,GAAG,GAA6B,CAAC;IAE1C,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE7C,MAAM,UAAU,GAAG;QACjB,SAAS;QACT,MAAM;QACN,UAAU;QACV,QAAQ;QACR,iBAAiB;QACjB,WAAW;QACX,aAAa;QACb,SAAS;QACT,MAAM;QACN,QAAQ;QACR,UAAU;QACV,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,kBAAkB;KACnB,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3D,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACnD,CAAC;IAED,4CAA4C;IAC5C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC,EAAE,CAAC;QACzE,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACpD,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IAED,sDAAsD;IACtD,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC5B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACjD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACjD,CAAC;IAED,4BAA4B;IAC5B,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IAClD,CAAC;IAED,6BAA6B;IAC7B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACvD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,GAAG,GAAG,GAA8B,CAAC;IAE3C,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7C,IACE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAClF,GAAG,CAAC,IAAc,CACnB;QAED,OAAO,KAAK,CAAC;IAEf,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/daemon/server.js

@@ -31,46 +31,52 @@ if (!socketPath) {
 // Map of photonName -> SessionManager (lazy initialized)
 const sessionManagers = new Map();
 const photonPaths = new Map(); // photonName -> photonPath
-let idleTimeout = 600000; // 10 minutes default
+const fileWatchers = new Map();
+const watchDebounce = new Map();
+let idleTimeout = 0; // Daemon stays alive — it manages persistent stateful data
 let idleTimer = null;
 // Track pending prompts waiting for user input
 const pendingPrompts = new Map();
 // Channel subscriptions for pub/sub
 const channelSubscriptions = new Map();
-const EVENT_BUFFER_SIZE = 30;
+/** Buffer retention window — events older than this are purged */
+const EVENT_BUFFER_DURATION_MS = 5 * 60 * 1000; // 5 minutes
 const channelEventBuffers = new Map();
 function bufferEvent(channel, message) {
     let buffer = channelEventBuffers.get(channel);
     if (!buffer) {
-        buffer = { events: [], nextId: 1 };
+        buffer = { events: [] };
         channelEventBuffers.set(channel, buffer);
     }
-    const eventId = buffer.nextId++;
+    const now = Date.now();
     const event = {
-        id: eventId,
+        id: now,
         channel,
         message,
-        timestamp: Date.now(),
+        timestamp: now,
     };
     buffer.events.push(event);
-    // Keep only last N events (circular buffer)
-    if (buffer.events.length > EVENT_BUFFER_SIZE) {
+    // Purge events older than retention window
+    const cutoff = now - EVENT_BUFFER_DURATION_MS;
+    while (buffer.events.length > 0 && buffer.events[0].timestamp < cutoff) {
         buffer.events.shift();
     }
-    return eventId;
+    return now;
 }
-function getEventsSince(channel, lastEventId) {
+function getEventsSince(channel, lastTimestamp) {
     const buffer = channelEventBuffers.get(channel);
     if (!buffer || buffer.events.length === 0) {
-        return { events: [], refreshNeeded: false };
+        // If client has a lastEventId but buffer is empty (e.g. daemon restarted),
+        // signal that a full refresh is needed — events were lost.
+        return { events: [], refreshNeeded: lastTimestamp > 0 };
     }
     const oldestEvent = buffer.events[0];
-    // If lastEventId is older than our oldest buffered event, refresh needed
-    if (lastEventId < oldestEvent.id) {
+    // Client's last timestamp is older than our oldest buffered event → stale, full sync needed
+    if (lastTimestamp < oldestEvent.timestamp) {
         return { events: [], refreshNeeded: true };
     }
-    // Find events to replay
-    const events = buffer.events.filter((e) => e.id > lastEventId);
+    // Delta sync: return events after the client's last timestamp
+    const events = buffer.events.filter((e) => e.timestamp > lastTimestamp);
     return { events, refreshNeeded: false };
 }
 // ════════════════════════════════════════════════════════════════════════════════
@@ -268,7 +274,9 @@ function startWebhookServer(port) {
         const expectedSecret = process.env.PHOTON_WEBHOOK_SECRET;
         if (expectedSecret) {
             const providedSecret = req.headers['x-webhook-secret'];
-            if (!providedSecret || typeof providedSecret !== 'string' || !timingSafeEqual(providedSecret, expectedSecret)) {
+            if (!providedSecret ||
+                typeof providedSecret !== 'string' ||
+                !timingSafeEqual(providedSecret, expectedSecret)) {
                 res.writeHead(401, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Invalid webhook secret' }));
                 return;
@@ -277,7 +285,9 @@ function startWebhookServer(port) {
         else if (!process.env.PHOTON_WEBHOOK_ALLOW_UNAUTHENTICATED) {
             // Security: require explicit opt-in for unauthenticated webhooks
             res.writeHead(403, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Webhook secret not configured. Set PHOTON_WEBHOOK_SECRET or PHOTON_WEBHOOK_ALLOW_UNAUTHENTICATED=true' }));
+            res.end(JSON.stringify({
+                error: 'Webhook secret not configured. Set PHOTON_WEBHOOK_SECRET or PHOTON_WEBHOOK_ALLOW_UNAUTHENTICATED=true',
+            }));
             return;
         }
         let args = {};
@@ -366,7 +376,8 @@ function publishToChannel(channel, message, excludeSocket) {
                     sentSockets.add(socket);
                 }
                 catch {
-                    // Socket write failed
+                    // Dead socket — remove from subscribers
+                    exactSubscribers.delete(socket);
                 }
             }
         }
@@ -384,7 +395,8 @@ function publishToChannel(channel, message, excludeSocket) {
                         sentSockets.add(socket);
                     }
                     catch {
-                        // Socket write failed
+                        // Dead socket — remove from subscribers
+                        wildcardSubscribers.delete(socket);
                     }
                 }
             }
@@ -418,6 +430,7 @@ async function getOrCreateSessionManager(photonName, photonPath) {
         manager = new SessionManager(pathToUse, photonName, idleTimeout, logger.child({ scope: photonName }));
         sessionManagers.set(photonName, manager);
         photonPaths.set(photonName, pathToUse);
+        watchPhotonFile(photonName, pathToUse);
         logger.info('Session manager initialized', { photonName });
         return manager;
     }
@@ -505,32 +518,32 @@ async function handleRequest(request, socket) {
         }
         subs.add(socket);
         logger.info('Client subscribed to channel', { channel, subscribers: subs.size });
-        // Replay missed events if lastEventId provided
+        // Replay missed events if lastEventId (timestamp) provided
         if (lastEventId !== undefined) {
-            const parsedLastEventId = parseInt(String(lastEventId), 10) || 0;
-            const { events, refreshNeeded } = getEventsSince(channel, parsedLastEventId);
+            const lastTimestamp = parseInt(String(lastEventId), 10) || 0;
+            const { events, refreshNeeded } = getEventsSince(channel, lastTimestamp);
             if (refreshNeeded) {
-                // Send refresh-needed signal
+                // Stale: client's timestamp is older than buffer window → full sync needed
                 socket.write(JSON.stringify({
                     type: 'refresh_needed',
                     id: request.id,
                     channel,
                 }) + '\n');
-                logger.info('Replay: refresh needed', { channel, lastEventId });
+                logger.info('Stale client, full sync needed', { channel, lastTimestamp });
             }
             else if (events.length > 0) {
-                // Replay events
+                // Delta sync: replay missed events
                 for (const event of events) {
                     socket.write(JSON.stringify({
                         type: 'channel_message',
-                        id: `replay_${event.id}`,
-                        eventId: event.id,
+                        id: `replay_${event.timestamp}`,
+                        eventId: event.timestamp,
                         channel: event.channel,
                         message: event.message,
                         replay: true,
                     }) + '\n');
                 }
-                logger.info('Replayed events', { channel, count: events.length });
+                logger.info('Delta sync: replayed events', { channel, count: events.length });
             }
         }
         return {
@@ -565,11 +578,11 @@ async function handleRequest(request, socket) {
             data: { published: true, channel, eventId },
         };
     }
-    // Handle get_events_since (for event replay)
+    // Handle get_events_since (for delta sync / full sync detection)
     if (request.type === 'get_events_since') {
         const channel = request.channel;
-        const parsedLastEventId = parseInt(String(request.lastEventId || '0'), 10) || 0;
-        const { events, refreshNeeded } = getEventsSince(channel, parsedLastEventId);
+        const lastTimestamp = parseInt(String(request.lastEventId || '0'), 10) || 0;
+        const { events, refreshNeeded } = getEventsSince(channel, lastTimestamp);
         return {
             type: 'result',
             id: request.id,
@@ -620,7 +633,12 @@ async function handleRequest(request, socket) {
     if (request.type === 'schedule') {
         const photonName = request.photonName;
         if (!photonName) {
-            return { type: 'error', id: request.id, error: 'photonName required for scheduling' };
+            return {
+                type: 'error',
+                id: request.id,
+                error: 'photonName required for scheduling',
+                suggestion: 'Include photonName in the request payload',
+            };
         }
         const job = {
             id: request.jobId,
@@ -656,11 +674,21 @@ async function handleRequest(request, socket) {
     // Handle command execution
     if (request.type === 'command') {
         if (!request.method) {
-            return { type: 'error', id: request.id, error: 'Method name required' };
+            return {
+                type: 'error',
+                id: request.id,
+                error: 'Method name required',
+                suggestion: 'Specify the method to call: { method: "methodName" }',
+            };
         }
         const photonName = request.photonName;
         if (!photonName) {
-            return { type: 'error', id: request.id, error: 'photonName required for commands' };
+            return {
+                type: 'error',
+                id: request.id,
+                error: 'photonName required for commands',
+                suggestion: 'Include photonName in the request payload',
+            };
         }
         const sessionManager = await getOrCreateSessionManager(photonName, request.photonPath);
         if (!sessionManager) {
@@ -672,10 +700,53 @@ async function handleRequest(request, socket) {
         }
         try {
             const session = await sessionManager.getOrCreateSession(request.sessionId, request.clientType);
+            // ── Auto-recover from instance drift ─────────────────────────
+            // If the client tells us which instance it expects but the daemon
+            // session has drifted (e.g. session expired and was recreated as
+            // "default"), silently switch back to the correct instance.
+            if (request.instanceName && request.instanceName !== session.instanceName) {
+                logger.info('Instance drift detected, auto-switching', {
+                    from: session.instanceName || 'default',
+                    to: request.instanceName,
+                    sessionId: session.id,
+                });
+                await sessionManager.switchInstance(session.id, request.instanceName);
+            }
+            // ── Runtime-injected instance tools ──────────────────────────
+            if (request.method === '_use') {
+                const instanceName = String(request.args?.name ?? '');
+                await sessionManager.switchInstance(session.id, instanceName);
+                const label = instanceName || 'default';
+                return {
+                    type: 'result',
+                    id: request.id,
+                    success: true,
+                    data: { instance: label, message: `Switched to instance: ${label}` },
+                };
+            }
+            if (request.method === '_instances') {
+                const { InstanceStore } = await import('../context-store.js');
+                const store = new InstanceStore();
+                const instances = store.listInstances(photonName);
+                const current = session.instanceName || 'default';
+                // Ensure current instance is always in the list (may not have a state file yet)
+                if (!instances.includes(current)) {
+                    instances.push(current);
+                    instances.sort();
+                }
+                return {
+                    type: 'result',
+                    id: request.id,
+                    success: true,
+                    data: { instances, current },
+                };
+            }
+            // ─────────────────────────────────────────────────────────────
             logger.info('Executing request', {
                 method: request.method,
                 photon: photonName,
                 sessionId: session.id,
+                instance: session.instanceName || 'default',
             });
             setPromptHandler(createSocketPromptHandler(socket, request.id));
             const outputHandler = (emit) => {
@@ -686,6 +757,14 @@ async function handleRequest(request, socket) {
             };
             const result = await sessionManager.loader.executeTool(session.instance, request.method, request.args || {}, { outputHandler });
             setPromptHandler(null);
+            // Persist reactive state after each tool call
+            await persistInstanceState(session.instance, photonName, session.instanceName);
+            // Notify subscribers that state may have changed
+            publishToChannel(`${photonName}:state-changed`, {
+                event: 'state-changed',
+                method: request.method,
+                data: result,
+            }, socket);
             return { type: 'result', id: request.id, success: true, data: result };
         }
         catch (error) {
@@ -700,6 +779,144 @@ async function handleRequest(request, socket) {
     return { type: 'error', id: request.id, error: `Unknown request type: ${request.type}` };
 }
 // ════════════════════════════════════════════════════════════════════════════════
+// STATE PERSISTENCE
+// ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Persist reactive collection state to disk after each tool call.
+ * Scans the instance for properties with _propertyName (ReactiveArray/Map/Set markers)
+ * and serializes them to the instance-specific state file.
+ */
+/** Cache of state keys per photon (extracted once from source) */
+const stateKeysCache = new Map();
+/**
+ * Get the state property keys for a photon by extracting constructor params.
+ * State params: non-primitive with default on @stateful photon.
+ */
+async function getStateKeys(photonName, photonPath) {
+    if (stateKeysCache.has(photonName)) {
+        return stateKeysCache.get(photonName);
+    }
+    try {
+        const { SchemaExtractor } = await import('@portel/photon-core');
+        const fsPromises = await import('fs/promises');
+        const source = await fsPromises.readFile(photonPath, 'utf-8');
+        const extractor = new SchemaExtractor();
+        const injections = extractor.resolveInjections(source, photonName);
+        const keys = injections
+            .filter((inj) => inj.injectionType === 'state')
+            .map((inj) => inj.stateKey);
+        stateKeysCache.set(photonName, keys);
+        logger.debug('State keys extracted', { photon: photonName, keys });
+        return keys;
+    }
+    catch (error) {
+        logger.error('Failed to extract state keys', {
+            photon: photonName,
+            error: getErrorMessage(error),
+        });
+        return [];
+    }
+}
+/**
+ * Persist reactive collection state to disk after each tool call.
+ * Only persists properties identified as 'state' injection type
+ * (non-primitive constructor params with defaults on @stateful photons).
+ */
+async function persistInstanceState(instance, photonName, instanceName) {
+    try {
+        const photonPath = photonPaths.get(photonName);
+        if (!photonPath)
+            return;
+        const keys = await getStateKeys(photonName, photonPath);
+        if (keys.length === 0)
+            return;
+        // instance is PhotonMCPClass wrapper — actual user class is instance.instance
+        const target = instance?.instance ?? instance;
+        const snapshot = {};
+        for (const key of keys) {
+            const value = target[key];
+            if (value === undefined)
+                continue;
+            if (value && typeof value === 'object' && value._propertyName) {
+                // ReactiveArray/Map/Set — serialize underlying data
+                snapshot[key] = value.toJSON ? value.toJSON() : globalThis.Array.from(value);
+            }
+            else {
+                // Plain value (array, object, etc.)
+                snapshot[key] = value;
+            }
+        }
+        if (Object.keys(snapshot).length > 0) {
+            const { getInstanceStatePath } = await import('../context-store.js');
+            const statePath = getInstanceStatePath(photonName, instanceName);
+            const fsPromises = await import('fs/promises');
+            const path = await import('path');
+            await fsPromises.mkdir(path.dirname(statePath), { recursive: true });
+            await fsPromises.writeFile(statePath, JSON.stringify(snapshot, null, 2));
+            logger.debug('Persisted state', { photon: photonName, instance: instanceName || 'default' });
+        }
+    }
+    catch (error) {
+        logger.error('Failed to persist state', {
+            photon: photonName,
+            error: getErrorMessage(error),
+        });
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════════
+// FILE WATCHING (Auto Hot-Reload)
+// ════════════════════════════════════════════════════════════════════════════════
+function watchPhotonFile(photonName, photonPath) {
+    if (fileWatchers.has(photonPath))
+        return;
+    try {
+        const watcher = fs.watch(photonPath, (eventType) => {
+            // Debounce: 100ms (same as Beam)
+            const existing = watchDebounce.get(photonPath);
+            if (existing)
+                clearTimeout(existing);
+            watchDebounce.set(photonPath, setTimeout(async () => {
+                watchDebounce.delete(photonPath);
+                // On macOS, editors like sed -i and some IDEs replace the file (new inode),
+                // which kills the watcher. Re-watch if file still exists.
+                if (eventType === 'rename') {
+                    unwatchPhotonFile(photonPath);
+                    if (fs.existsSync(photonPath)) {
+                        watchPhotonFile(photonName, photonPath);
+                    }
+                }
+                if (!fs.existsSync(photonPath))
+                    return;
+                logger.info('File changed, auto-reloading', { photonName, path: photonPath });
+                // Invalidate cached state keys so they're re-extracted from fresh source
+                stateKeysCache.delete(photonName);
+                await reloadPhoton(photonName, photonPath);
+            }, 100));
+        });
+        watcher.on('error', (err) => {
+            logger.warn('File watcher error', { photonName, error: getErrorMessage(err) });
+            unwatchPhotonFile(photonPath);
+        });
+        fileWatchers.set(photonPath, watcher);
+        logger.info('Watching photon file', { photonName, path: photonPath });
+    }
+    catch (err) {
+        logger.warn('Failed to watch photon file', { photonName, error: getErrorMessage(err) });
+    }
+}
+function unwatchPhotonFile(photonPath) {
+    const watcher = fileWatchers.get(photonPath);
+    if (watcher) {
+        watcher.close();
+        fileWatchers.delete(photonPath);
+    }
+    const timer = watchDebounce.get(photonPath);
+    if (timer) {
+        clearTimeout(timer);
+        watchDebounce.delete(photonPath);
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════════
 // HOT RELOAD
 // ════════════════════════════════════════════════════════════════════════════════
 async function reloadPhoton(photonName, newPhotonPath) {
@@ -707,8 +924,9 @@ async function reloadPhoton(photonName, newPhotonPath) {
         logger.info('Hot-reloading photon', { photonName, path: newPhotonPath });
         const sessionManager = sessionManagers.get(photonName);
         if (!sessionManager) {
-            // First time - just register the path
+            // First time - just register the path and start watching
             photonPaths.set(photonName, newPhotonPath);
+            watchPhotonFile(photonName, newPhotonPath);
             return { success: true, sessionsUpdated: 0 };
         }
         await sessionManager.loader.reloadFile(newPhotonPath);
@@ -862,6 +1080,10 @@ function shutdown() {
     jobTimers.clear();
     scheduledJobs.clear();
     activeLocks.clear();
+    // Close file watchers and debounce timers
+    for (const photonPath of fileWatchers.keys()) {
+        unwatchPhotonFile(photonPath);
+    }
     for (const manager of sessionManagers.values()) {
         manager.destroy();
     }