@portel/photon 1.22.0 → 1.23.0

package/dist/daemon/server.js

@@ -15,13 +15,16 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import { SessionManager } from './session-manager.js';
+import { transferHotReloadState } from './hot-reload-state.js';
+import { resolveWithGlobalFallback } from './session-resolver.js';
 import { isValidDaemonRequest, } from './protocol.js';
-import { setPromptHandler, setBroker } from '@portel/photon-core';
+import { setPromptHandler, setBroker, touchBase, getPhotonSchedulesDir, getPhotonStateLogPath, listActiveBases, pruneBasesRegistry, resolvePhotonPath, } from '@portel/photon-core';
 import { getDefaultContext } from '../context.js';
 import { createLogger } from '../shared/logger.js';
 import { getErrorMessage } from '../shared/error-handler.js';
-import { timingSafeEqual, readBody, SimpleRateLimiter } from '../shared/security.js';
+import { timingSafeEqual, readBody, SimpleRateLimiter, ipInAllowlist, parseAllowlistEnv, } from '../shared/security.js';
 import { audit } from '../shared/audit.js';
+import { recordExecution, previewResult, readExecutionHistory, sweepAllBases as sweepExecutionHistoryBases, } from './execution-history.js';
 import { WorkerManager } from './worker-manager.js';
 import fastJsonPatch from 'fast-json-patch';
 import { getOwnerFilePath, isPidAlive, readOwnerRecord, removeOwnerRecord, waitForPidExit, writeOwnerRecord, } from './ownership.js';
@@ -134,7 +137,11 @@ const connectedSockets = new Set();
 let daemonServer = null;
 /** Whether the daemon is shutting down (reject new commands) */
 let isShuttingDown = false;
-/** Tracks active executeTool calls per composite key */
+/**
+ * Tracks active executeTool calls per (photon, base) composite key.
+ * Typed on PhotonCompositeKey so bare-string `.get(photonName)` stops
+ * compiling — same guardrail as the schedule maps.
+ */
 const activeExecutions = new Map();
 /** Per-key mutex to prevent concurrent reloads (format-on-save race) */
 const reloadMutex = new Map();
@@ -164,24 +171,91 @@ function untrackExecution(key) {
 const sessionManagers = new Map();
 const photonPaths = new Map(); // compositeKey -> photonPath
 const workingDirs = new Map(); // compositeKey -> workingDir
+// Keyed by resolved file path (realpathSync), not composite key.
 const fileWatchers = new Map();
-const watchDebounce = new Map();
+const watchDebounce = new Map(); // keyed by base:filename, not photon
+const photonSourceStats = new Map();
+/** Snapshot the stat fields we use as change signal. Null on ENOENT etc. */
+function statOrNull(filePath) {
+    try {
+        const s = fs.statSync(filePath);
+        return { mtimeMs: s.mtimeMs, size: s.size, ino: s.ino };
+    }
+    catch {
+        return null;
+    }
+}
+/** Record the current stat for a photon after a successful load or reload. */
+function recordPhotonSourceStat(key, photonPath) {
+    if (!photonPath)
+        return;
+    const s = statOrNull(photonPath);
+    if (s)
+        photonSourceStats.set(key, s);
+}
+/**
+ * Compare the current file stat against the last-recorded stat. If the
+ * file has changed since the cached photon was loaded, trigger a
+ * synchronous reload before returning. On any error (missing file,
+ * reload failure), the call returns without throwing so dispatch can
+ * surface a richer error downstream.
+ */
+async function statGate(key, photonName, photonPath, workingDir) {
+    if (!photonPath)
+        return;
+    const cached = photonSourceStats.get(key);
+    if (!cached) {
+        // No baseline yet — record what's there now and let this request run on
+        // the current (just-loaded) instance.
+        recordPhotonSourceStat(key, photonPath);
+        return;
+    }
+    const current = statOrNull(photonPath);
+    if (!current)
+        return;
+    if (current.mtimeMs === cached.mtimeMs &&
+        current.size === cached.size &&
+        current.ino === cached.ino) {
+        return;
+    }
+    logger.info('stat-gate: source changed since last load, syncing reload', {
+        photon: photonName,
+        path: photonPath,
+        prevMtime: cached.mtimeMs,
+        newMtime: current.mtimeMs,
+    });
+    try {
+        const result = await reloadPhoton(photonName, photonPath, workingDir);
+        if (result.success) {
+            photonSourceStats.set(key, current);
+        }
+    }
+    catch (err) {
+        logger.warn('stat-gate: reload failed — continuing with stale instance', {
+            photon: photonName,
+            error: getErrorMessage(err),
+        });
+    }
+}
 // parentDir -> SafeWatcher: one watcher per unique parent directory
 const parentDirWatchers = new Map();
 // workingDir -> inode: recorded at watch time for rename-vs-delete detection
 const workingDirInodes = new Map();
 // workingDir -> SafeWatcher: watches {workingDir}/state/ for photon subdir deletions
 const stateDirWatchers = new Map();
+// basePath -> SafeWatcher: watches a PHOTON_DIR root for .photon.ts edits so
+// @scheduled cron changes and @webhook additions reach the declared-set
+// without a daemon restart. See watchBaseForProactiveMetadata().
+const baseDirWatchers = new Map();
+import { compositeKey as _compositeKey, declaredKey as _declaredKey, webhookKey as _webhookKey, locationKey as _locationKey, findByPhoton, asScheduleKey, } from './registry-keys.js';
 /**
  * Create a composite key from photonName + workingDir for map lookups.
- * When workingDir is the default (~/.photon), returns just the photonName
- * for backwards compatibility.
+ * Delegates to registry-keys.ts (the single source of truth for key shapes).
+ * Return type is branded so every caller that indexes a PhotonCompositeKey
+ * map has to route through this helper — bare-string lookups won't compile.
  */
 function compositeKey(photonName, workingDir) {
-    if (!workingDir || workingDir === getDefaultContext().baseDir)
-        return photonName;
-    const dirHash = crypto.createHash('sha256').update(workingDir).digest('hex').slice(0, 8);
-    return `${photonName}:${dirHash}`;
+    return _compositeKey(photonName, workingDir, getDefaultContext().baseDir);
 }
 /**
  * Determine if a photon should run in a worker thread.
@@ -351,6 +425,14 @@ staleMapCleanupInterval.unref();
 // ════════════════════════════════════════════════════════════════════════════════
 // SCHEDULED JOBS
 // ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Scheduled-jobs registry. Keyed by ScheduleKey (branded) so bare-string
+ * lookups fail at compile time — the same guardrail as declaredSchedules.
+ * scheduleJob()/unscheduleJob() are the ONLY correct way to mutate the
+ * (scheduledJobs, jobTimers) pair together. Direct map writes leave one
+ * of the two half-populated and were the cause of at least two rounds of
+ * codex regression findings.
+ */
 const scheduledJobs = new Map();
 const jobTimers = new Map();
 function parseCronField(field, min, max) {
@@ -509,17 +591,21 @@ function scheduleJob(job) {
         logger.error('Invalid cron expression', { jobId: job.id, cron: job.cron });
         return false;
     }
+    // ScheduledJob.id is typed string at the protocol boundary, but every
+    // producer inside this daemon creates it via declaredKey(). Coerce once
+    // here so downstream map access gets the branded type.
+    const jobKey = asScheduleKey(job.id);
     job.nextRun = nextRun;
-    scheduledJobs.set(job.id, job);
-    const existingTimer = jobTimers.get(job.id);
+    scheduledJobs.set(jobKey, job);
+    const existingTimer = jobTimers.get(jobKey);
     if (existingTimer) {
         clearTimeout(existingTimer);
     }
     const delay = nextRun - Date.now();
     const timer = setTimeout(() => {
-        void runJob(job.id);
+        void runJob(jobKey);
     }, delay);
-    jobTimers.set(job.id, timer);
+    jobTimers.set(jobKey, timer);
     logger.info('Job scheduled', {
         jobId: job.id,
         method: job.method,
@@ -533,7 +619,24 @@ async function runJob(jobId) {
     if (!job)
         return;
     const key = compositeKey(job.photonName, job.workingDir);
-    const sessionManager = sessionManagers.get(key);
+    let sessionManager = sessionManagers.get(key);
+    // Lazy-load: schedules registered proactively at boot carry the photon's
+    // source path on the job, so we can spin up the session when the timer
+    // fires rather than require the photon to be invoked manually first.
+    if (!sessionManager && job.photonPath) {
+        try {
+            sessionManager =
+                (await getOrCreateSessionManager(job.photonName, job.photonPath, job.workingDir)) ??
+                    undefined;
+        }
+        catch (err) {
+            logger.warn('Lazy-load for scheduled job failed', {
+                jobId,
+                photon: job.photonName,
+                error: getErrorMessage(err),
+            });
+        }
+    }
     if (!sessionManager) {
         logger.warn('Cannot run job - photon not initialized', { jobId, photon: job.photonName });
         scheduleJob(job); // Reschedule anyway
@@ -541,9 +644,13 @@ async function runJob(jobId) {
     }
     logger.info('Running scheduled job', { jobId, method: job.method, photon: job.photonName });
     trackExecution(key);
+    const startTs = Date.now();
+    let status = 'success';
+    let errorMessage;
+    let result;
     try {
         const session = await sessionManager.getOrCreateSession('scheduler', 'scheduler');
-        await sessionManager.loader.executeTool(session.instance, job.method, job.args || {});
+        result = await sessionManager.loader.executeTool(session.instance, job.method, job.args || {});
         job.lastRun = Date.now();
         job.runCount++;
         // Update persisted schedule file if this came from ScheduleProvider
@@ -560,16 +667,27 @@ async function runJob(jobId) {
         logger.info('Job completed', { jobId, method: job.method, runCount: job.runCount });
     }
     catch (error) {
-        logger.error('Job failed', { jobId, method: job.method, error: getErrorMessage(error) });
+        status = 'error';
+        errorMessage = getErrorMessage(error);
+        logger.error('Job failed', { jobId, method: job.method, error: errorMessage });
         publishToChannel(`jobs:${job.photonName}`, {
             event: 'job-failed',
             jobId,
             method: job.method,
-            error: getErrorMessage(error),
+            error: errorMessage,
         });
     }
     finally {
         untrackExecution(key);
+        recordExecution(job.photonName, {
+            ts: Date.now(),
+            jobId,
+            method: job.method,
+            durationMs: Date.now() - startTs,
+            status,
+            errorMessage,
+            outputPreview: status === 'success' ? previewResult(result) : undefined,
+        }, job.workingDir);
     }
     scheduleJob(job);
 }
@@ -585,6 +703,60 @@ function unscheduleJob(jobId) {
     }
     return existed;
 }
+/**
+ * Resolve the canonical schedules dir for a photon under the Option B
+ * contract: {workingDir || default baseDir}/.data/{photonName}/schedules/.
+ *
+ * KNOWN LIMITATION: this path uses only the bare `photonName` — no
+ * namespace/subdirectory is threaded through. Two photons with the same
+ * filename under different subdirectories in one PHOTON_DIR (e.g.
+ * `alice/foo.photon.ts` and `bob/foo.photon.ts`) resolve to the same
+ * `.data/foo/schedules/` tree and therefore share schedule state. This
+ * predates the post-v1.22.1 multi-base work and fixing it cleanly
+ * requires photon-core to accept a namespace in getPhotonSchedulesDir
+ * and every scheduled-job record to carry that namespace. Do NOT load
+ * namespaced duplicates of a photon into the same daemon until this
+ * is resolved. Flagged by codex review 2026-04-19.
+ */
+function resolveScheduleDir(photonName, workingDir) {
+    return getPhotonSchedulesDir('', photonName, workingDir || getDefaultContext().baseDir);
+}
+/**
+ * Root of the legacy schedules tree (pre-Option-B layout).
+ * Honors `PHOTON_SCHEDULES_DIR` only for the one-release deprecation
+ * window; production code should rely on the per-PHOTON_DIR layout.
+ */
+let _schedulesEnvWarned = false;
+function resolveLegacySchedulesRoot() {
+    const override = process.env.PHOTON_SCHEDULES_DIR;
+    if (override) {
+        if (!_schedulesEnvWarned) {
+            _schedulesEnvWarned = true;
+            logger.warn('PHOTON_SCHEDULES_DIR is deprecated and will be removed in the next minor release. ' +
+                'Schedules now live under {PHOTON_DIR}/.data/{photon}/schedules/ per Option B.', { path: override });
+        }
+        return override;
+    }
+    return path.join(os.homedir(), '.photon', 'schedules');
+}
+/**
+ * Legacy schedules dir (pre-Option-B), read-only compatibility path.
+ * Kept for the one-release transition window so schedules created before
+ * this change continue to be discoverable.
+ */
+function resolveLegacyScheduleDir(photonName) {
+    return path.join(resolveLegacySchedulesRoot(), photonName.replace(/[^a-zA-Z0-9_-]/g, '_'));
+}
+/** Locate a persisted schedule file, preferring the new location. */
+function findPersistedScheduleFile(photonName, taskId, workingDir) {
+    const newPath = path.join(resolveScheduleDir(photonName, workingDir), `${taskId}.json`);
+    if (fs.existsSync(newPath))
+        return newPath;
+    const legacyPath = path.join(resolveLegacyScheduleDir(photonName), `${taskId}.json`);
+    if (fs.existsSync(legacyPath))
+        return legacyPath;
+    return null;
+}
 /** Update persisted schedule file after job execution */
 function updatePersistedSchedule(jobId, photonName, updates) {
     // Handle both ScheduleProvider jobs (photonName:sched:uuid) and IPC jobs (photonName:*:ipc:uuid)
@@ -593,8 +765,10 @@ function updatePersistedSchedule(jobId, photonName, updates) {
     if (!schedMatch && !ipcMatch)
         return;
     const taskId = schedMatch ? schedMatch[1] : ipcMatch[1];
-    const schedulesDir = path.join(process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules'), photonName.replace(/[^a-zA-Z0-9_-]/g, '_'));
-    const filePath = path.join(schedulesDir, `${taskId}.json`);
+    const workingDir = scheduledJobs.get(asScheduleKey(jobId))?.workingDir;
+    const filePath = findPersistedScheduleFile(photonName, taskId, workingDir);
+    if (!filePath)
+        return;
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
         const task = JSON.parse(content);
@@ -610,7 +784,7 @@ function updatePersistedSchedule(jobId, photonName, updates) {
 }
 /** Persist an IPC-created schedule job to disk for daemon restart recovery */
 function persistIpcSchedule(job) {
-    const schedulesDir = path.join(process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules'), job.photonName.replace(/[^a-zA-Z0-9_-]/g, '_'));
+    const schedulesDir = resolveScheduleDir(job.photonName, job.workingDir);
     try {
         fs.mkdirSync(schedulesDir, { recursive: true });
     }
@@ -652,106 +826,699 @@ function deletePersistedIpcSchedule(jobId, photonName) {
     if (!match)
         return;
     const taskId = match[1];
-    const schedulesDir = path.join(process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules'), photonName.replace(/[^a-zA-Z0-9_-]/g, '_'));
-    const filePath = path.join(schedulesDir, `${taskId}.json`);
+    const workingDir = scheduledJobs.get(asScheduleKey(jobId))?.workingDir;
+    const filePath = findPersistedScheduleFile(photonName, taskId, workingDir);
+    if (!filePath)
+        return;
     try {
-        if (fs.existsSync(filePath)) {
-            fs.unlinkSync(filePath);
-            logger.debug('Deleted persisted IPC schedule', { jobId, path: filePath });
-        }
+        fs.unlinkSync(filePath);
+        logger.debug('Deleted persisted IPC schedule', { jobId, path: filePath });
     }
     catch {
         // Ignore — file may already be gone
     }
 }
-/** Load all persisted schedules from disk on daemon startup */
-function loadAllPersistedSchedules() {
-    const baseDir = process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules');
-    if (!fs.existsSync(baseDir))
+/**
+ * Process IPC schedule files from one photon's schedules directory.
+ * Mutates loadedCount / skippedCount via the returned counters.
+ */
+function loadIpcSchedulesFromDir(schedulesPath, ttlMs) {
+    let loaded = 0;
+    let skipped = 0;
+    let files;
+    try {
+        files = fs.readdirSync(schedulesPath).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return { loaded, skipped };
+    }
+    for (const file of files) {
+        const filePath = path.join(schedulesPath, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const task = JSON.parse(content);
+            // Skip non-IPC jobs (ScheduleProvider handles its own)
+            if (task.source !== 'ipc')
+                continue;
+            // Validate required fields
+            if (!task.id || !task.method || !task.cron || !task.photonName) {
+                logger.warn('Skipping invalid persisted schedule', { file: filePath });
+                skipped++;
+                continue;
+            }
+            // TTL check: skip jobs not executed in 30+ days
+            const lastExec = task.lastExecutionAt ? new Date(task.lastExecutionAt).getTime() : 0;
+            const created = task.createdAt ? new Date(task.createdAt).getTime() : 0;
+            const lastActivity = Math.max(lastExec, created);
+            if (lastActivity > 0 && Date.now() - lastActivity > ttlMs) {
+                logger.info('Removing expired schedule (TTL)', {
+                    jobId: task.id,
+                    lastActivity: new Date(lastActivity).toISOString(),
+                });
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch {
+                    /* ignore */
+                }
+                skipped++;
+                continue;
+            }
+            // Skip if already registered (another source may have loaded it)
+            if (scheduledJobs.has(task.id))
+                continue;
+            const job = {
+                id: task.id,
+                method: task.method,
+                args: task.args || {},
+                cron: task.cron,
+                runCount: task.executionCount || 0,
+                createdAt: created || Date.now(),
+                createdBy: task.createdBy,
+                photonName: task.photonName,
+                workingDir: task.workingDir,
+            };
+            if (scheduleJob(job)) {
+                loaded++;
+            }
+            else {
+                logger.warn('Failed to schedule persisted job (invalid cron?)', { jobId: task.id });
+                skipped++;
+            }
+        }
+        catch (err) {
+            logger.warn('Failed to load persisted schedule file', {
+                file: filePath,
+                error: getErrorMessage(err),
+            });
+            skipped++;
+        }
+    }
+    return { loaded, skipped };
+}
+/**
+ * One-time sweep of legacy IPC schedules from ~/.photon/schedules/ to the
+ * new per-base location. Only moves files that carry a `workingDir` field
+ * (IPC-originated schedules have this); ScheduleProvider-originated files
+ * that lack `workingDir` are left in place and continue to be read via the
+ * legacy fallback in autoRegisterFromMetadata until the photon that owns
+ * them runs under the new layout and regenerates them.
+ *
+ * Idempotent: files already moved are no longer at the legacy path, so the
+ * next startup is a no-op for them. Called before loadAllPersistedSchedules.
+ */
+function migrateLegacyIpcSchedules() {
+    const legacyRoot = resolveLegacySchedulesRoot();
+    if (!fs.existsSync(legacyRoot))
         return;
-    let loadedCount = 0;
-    let skippedCount = 0;
+    let moved = 0;
+    let kept = 0;
+    let photonDirs;
+    try {
+        photonDirs = fs.readdirSync(legacyRoot, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const dir of photonDirs) {
+        if (!dir.isDirectory())
+            continue;
+        const photonLegacyDir = path.join(legacyRoot, dir.name);
+        let files;
+        try {
+            files = fs.readdirSync(photonLegacyDir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const legacyPath = path.join(photonLegacyDir, file);
+            try {
+                const content = fs.readFileSync(legacyPath, 'utf-8');
+                const task = JSON.parse(content);
+                // Only migrate IPC-sourced files with a known working dir.
+                if (task.source !== 'ipc' || !task.workingDir || typeof task.workingDir !== 'string') {
+                    kept++;
+                    continue;
+                }
+                const destDir = resolveScheduleDir(task.photonName || dir.name, task.workingDir);
+                const destPath = path.join(destDir, file);
+                // Skip if the destination already has content (e.g. a previous partial
+                // migration succeeded); don't overwrite.
+                if (fs.existsSync(destPath)) {
+                    kept++;
+                    continue;
+                }
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.renameSync(legacyPath, destPath);
+                moved++;
+            }
+            catch {
+                kept++;
+            }
+        }
+        // If the legacy photon dir is now empty, remove it to keep the tree tidy.
+        try {
+            if (fs.readdirSync(photonLegacyDir).length === 0) {
+                fs.rmdirSync(photonLegacyDir);
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    if (moved > 0) {
+        logger.info('Migrated legacy IPC schedules to per-base location', { moved, kept });
+    }
+}
+/**
+ * Load all persisted IPC schedules from disk on daemon startup.
+ *
+ * Iterates every PHOTON_DIR recorded in the bases registry (`listActiveBases`)
+ * and scans each base's `{base}/.data/<photon>/schedules/` for IPC schedule
+ * records. Also scans the legacy flat dir (`~/.photon/schedules/` or
+ * `PHOTON_SCHEDULES_DIR`) for backwards compatibility with schedules that
+ * haven't yet been migrated.
+ */
+function loadAllPersistedSchedules() {
     const TTL_DAYS = 30;
     const ttlMs = TTL_DAYS * 24 * 60 * 60 * 1000;
-    try {
-        const photonDirs = fs.readdirSync(baseDir, { withFileTypes: true });
+    let loadedCount = 0;
+    let skippedCount = 0;
+    const scannedDirs = new Set();
+    const scanFlatRoot = (root) => {
+        if (!fs.existsSync(root))
+            return;
+        let photonDirs;
+        try {
+            photonDirs = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch (err) {
+            logger.warn('Failed to scan schedules directory', {
+                dir: root,
+                error: getErrorMessage(err),
+            });
+            return;
+        }
         for (const dir of photonDirs) {
             if (!dir.isDirectory())
                 continue;
-            const schedulesPath = path.join(baseDir, dir.name);
-            const files = fs.readdirSync(schedulesPath).filter((f) => f.endsWith('.json'));
-            for (const file of files) {
-                const filePath = path.join(schedulesPath, file);
+            const schedulesPath = path.join(root, dir.name);
+            if (scannedDirs.has(schedulesPath))
+                continue;
+            scannedDirs.add(schedulesPath);
+            const result = loadIpcSchedulesFromDir(schedulesPath, ttlMs);
+            loadedCount += result.loaded;
+            skippedCount += result.skipped;
+        }
+    };
+    const scanBaseDataRoot = (baseDir) => {
+        const dataRoot = path.join(baseDir, '.data');
+        if (!fs.existsSync(dataRoot))
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dataRoot, { withFileTypes: true });
+        }
+        catch (err) {
+            logger.warn('Failed to scan base schedules', {
+                base: baseDir,
+                error: getErrorMessage(err),
+            });
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Skip reserved buckets (_global, _sessions, .cache, tasks, .migrated, etc.)
+            if (entry.name.startsWith('_') || entry.name.startsWith('.') || entry.name === 'tasks') {
+                continue;
+            }
+            const schedulesPath = path.join(dataRoot, entry.name, 'schedules');
+            if (!fs.existsSync(schedulesPath))
+                continue;
+            if (scannedDirs.has(schedulesPath))
+                continue;
+            scannedDirs.add(schedulesPath);
+            const result = loadIpcSchedulesFromDir(schedulesPath, ttlMs);
+            loadedCount += result.loaded;
+            skippedCount += result.skipped;
+        }
+    };
+    // Scan every PHOTON_DIR we've ever served. Prune dead entries first so a
+    // deleted project folder doesn't emit warnings each startup.
+    const pruned = pruneBasesRegistry();
+    if (pruned.length > 0) {
+        logger.info('Pruned bases that no longer exist', {
+            removed: pruned.map((b) => b.path),
+        });
+    }
+    const bases = listActiveBases();
+    // Always include the default base even if the registry hasn't recorded it yet.
+    const defaultBase = getDefaultContext().baseDir;
+    if (!bases.some((b) => b.path === path.resolve(defaultBase))) {
+        scanBaseDataRoot(defaultBase);
+    }
+    for (const base of bases) {
+        scanBaseDataRoot(base.path);
+    }
+    // Legacy location for schedules that predate the per-base layout.
+    scanFlatRoot(resolveLegacySchedulesRoot());
+    if (loadedCount > 0 || skippedCount > 0) {
+        logger.info('Loaded persisted schedules', { loaded: loadedCount, skipped: skippedCount });
+    }
+}
+/**
+ * Boot-time discovery of `@scheduled` and `@webhook` tags across every
+ * known PHOTON_DIR. Before this ran, scheduled methods on a photon that
+ * had never been invoked would silently not fire, and webhook routes
+ * were only registered on first invocation. Now both work from the
+ * moment a photon file exists under a registered base.
+ *
+ * We never INSTANTIATE the photon here — only parse its source with
+ * the schema extractor to read tag metadata. When the schedule's cron
+ * fires (or a webhook request arrives), the daemon lazy-loads the
+ * photon via the normal session-manager path.
+ */
+/**
+ * Re-extract @scheduled and @webhook metadata for a single source file
+ * and reconcile the declaredSchedules / webhookRoutes maps in place.
+ * Returns true if anything changed (caller can re-sync active schedules
+ * and fan out a schedules-changed event).
+ *
+ * Shared between boot discovery and the live watcher — any behavior
+ * change here benefits both paths.
+ */
+async function scanOneForProactiveMetadata(photonName, filePath, workingDir) {
+    const core = await import('@portel/photon-core');
+    const SchemaExtractor = core.SchemaExtractor;
+    let source;
+    try {
+        const fsp = await import('fs/promises');
+        source = await fsp.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        // File may have been deleted/renamed mid-flight — drop its declarations.
+        // Scope to workingDir so a missing copy in base A doesn't wipe base B's
+        // declarations of the same photon name.
+        return dropProactiveMetadataFor(photonName, workingDir);
+    }
+    if (!/@(scheduled|cron|webhook)\b/.test(source) && !/\basync\s+handle[A-Z]/.test(source)) {
+        // No proactive tags anymore — clear anything we had for this photon.
+        return dropProactiveMetadataFor(photonName, workingDir);
+    }
+    let changed = false;
+    let meta;
+    try {
+        const extractor = new SchemaExtractor();
+        meta = extractor.extractAllFromSource(source);
+    }
+    catch (err) {
+        logger.warn('Metadata re-scan: extract failed', {
+            photon: photonName,
+            path: filePath,
+            error: getErrorMessage(err),
+        });
+        return false;
+    }
+    // Collect the new shape, then diff against current state so callers
+    // only fire change events on actual differences.
+    // Typed with the branded ScheduleKey so the diff loop against
+    // declaredSchedules below can feed its keys straight into .get/.set.
+    // See src/daemon/registry-keys.ts for the branded-key rationale.
+    const nextSchedules = new Map();
+    const nextRoutes = new Map(); // routePath → methodName
+    for (const rawTool of meta.tools) {
+        const tool = rawTool;
+        if (tool.scheduled) {
+            nextSchedules.set(declaredKey(photonName, tool.name, workingDir), {
+                photon: photonName,
+                method: tool.name,
+                cron: tool.scheduled,
+                photonPath: filePath,
+                workingDir,
+            });
+        }
+        if (tool.webhook !== undefined) {
+            const routePath = typeof tool.webhook === 'string' ? tool.webhook : tool.name;
+            nextRoutes.set(routePath, tool.name);
+        }
+    }
+    // Schedules diff — add/update new, remove stale entries owned by this photon
+    // AT THIS PHOTON_DIR. Scoping by workingDir matters: another base may have
+    // the same photon+method scheduled and we must not stomp on it.
+    const resolvedWorkingDir = workingDir ? path.resolve(workingDir) : undefined;
+    const existingScheduleKeys = new Set(Array.from(declaredSchedules.entries())
+        .filter(([, v]) => {
+        if (v.photon !== photonName)
+            return false;
+        const vBase = v.workingDir ? path.resolve(v.workingDir) : undefined;
+        return vBase === resolvedWorkingDir;
+    })
+        .map(([k]) => k));
+    for (const [key, decl] of nextSchedules) {
+        const prev = declaredSchedules.get(key);
+        if (!prev ||
+            prev.cron !== decl.cron ||
+            prev.photonPath !== decl.photonPath ||
+            prev.workingDir !== decl.workingDir) {
+            declaredSchedules.set(key, decl);
+            changed = true;
+        }
+        existingScheduleKeys.delete(key);
+    }
+    for (const staleKey of existingScheduleKeys) {
+        declaredSchedules.delete(staleKey);
+        changed = true;
+    }
+    // Webhooks diff — keyed per (base, photon) so multi-base setups can
+    // register the same photon name in two PHOTON_DIRs without collision.
+    const wKey = webhookKey(photonName, workingDir);
+    const prevEntry = webhookRoutes.get(wKey);
+    const prevRoutes = prevEntry?.routes;
+    const prevKeys = prevRoutes ? Array.from(prevRoutes.keys()) : [];
+    const nextKeys = Array.from(nextRoutes.keys());
+    if (nextKeys.length > 0) {
+        webhookRoutes.set(wKey, { photon: photonName, routes: nextRoutes, workingDir });
+        if (prevKeys.length !== nextKeys.length ||
+            prevKeys.some((k) => nextRoutes.get(k) !== prevRoutes?.get(k)) ||
+            prevEntry?.workingDir !== workingDir) {
+            changed = true;
+        }
+    }
+    else if (prevEntry) {
+        webhookRoutes.delete(wKey);
+        changed = true;
+    }
+    proactivePhotonLocations.set(locationKey(photonName, workingDir), {
+        photon: photonName,
+        photonPath: filePath,
+        workingDir,
+    });
+    return changed;
+}
+/** Remove all proactive-metadata entries owned by a photon. */
+/**
+ * Drop proactive declarations for a photon. When `workingDir` is supplied,
+ * scope the deletion to that PHOTON_DIR — required for multi-base setups
+ * where the same photon name can legitimately exist in two registered
+ * bases. Without scoping, deleting (or briefly failing to read) one copy
+ * would silently wipe the other base's schedules + webhooks.
+ *
+ * webhookRoutes is currently keyed by photon name only and isn't multi-base
+ * aware; we only delete that map's entry when no working dir is supplied
+ * (the legacy "wipe everything" path).
+ */
+function dropProactiveMetadataFor(photonName, workingDir) {
+    let changed = false;
+    const resolvedDir = workingDir ? path.resolve(workingDir) : undefined;
+    for (const [key, decl] of declaredSchedules.entries()) {
+        if (decl.photon !== photonName)
+            continue;
+        if (resolvedDir) {
+            const declDir = decl.workingDir ? path.resolve(decl.workingDir) : undefined;
+            if (declDir !== resolvedDir)
+                continue;
+        }
+        declaredSchedules.delete(key);
+        changed = true;
+    }
+    // Webhook routes are keyed by (base, photon). If a workingDir was
+    // supplied, delete only that exact key; otherwise remove every entry
+    // for this photon name across bases (legacy "wipe everything" path).
+    if (resolvedDir) {
+        const wKey = webhookKey(photonName, resolvedDir);
+        if (webhookRoutes.delete(wKey))
+            changed = true;
+    }
+    else {
+        for (const key of Array.from(webhookRoutes.keys())) {
+            if (webhookRoutes.get(key)?.photon === photonName) {
+                webhookRoutes.delete(key);
+                changed = true;
+            }
+        }
+    }
+    return changed;
+}
+async function discoverProactiveMetadataAtBoot() {
+    const baseCandidates = new Set();
+    const defaultBase = path.resolve(getDefaultContext().baseDir);
+    baseCandidates.add(defaultBase);
+    for (const base of listActiveBases())
+        baseCandidates.add(base.path);
+    let schedulesRegistered = 0;
+    let webhooksRegistered = 0;
+    let photonsScanned = 0;
+    // Lazy import to keep daemon startup cheap for users with no bases.
+    const core = await import('@portel/photon-core');
+    for (const basePath of baseCandidates) {
+        let photons;
+        try {
+            photons = await core.listPhotonFilesWithNamespace(basePath);
+        }
+        catch (err) {
+            logger.warn('Boot discovery: could not list photons in base', {
+                base: basePath,
+                error: getErrorMessage(err),
+            });
+            continue;
+        }
+        // Always pass basePath so declaredKey produces a stable resolved-path
+        // key. Previously this set workingDir=undefined for the default base,
+        // which yielded `-::photon:method` keys at boot — but the restore-from-
+        // active path used `declaredKey(entry, basePath)` and produced
+        // `<defaultBase>::photon:method`, so default-base schedules never
+        // re-armed after a daemon restart.
+        const workingDir = basePath;
+        for (const p of photons) {
+            photonsScanned++;
+            const before = {
+                schedules: Array.from(declaredSchedules.values()).filter((d) => d.photon === p.name).length,
+                routes: findWebhookEntriesFor(p.name).reduce((n, e) => n + e.routes.size, 0),
+            };
+            try {
+                await scanOneForProactiveMetadata(p.name, p.filePath, workingDir);
+            }
+            catch (err) {
+                logger.warn('Boot discovery: failed to extract metadata', {
+                    photon: p.name,
+                    path: p.filePath,
+                    error: getErrorMessage(err),
+                });
+                continue;
+            }
+            const after = {
+                schedules: Array.from(declaredSchedules.values()).filter((d) => d.photon === p.name).length,
+                routes: findWebhookEntriesFor(p.name).reduce((n, e) => n + e.routes.size, 0),
+            };
+            schedulesRegistered += Math.max(0, after.schedules - before.schedules);
+            webhooksRegistered += Math.max(0, after.routes - before.routes);
+        }
+    }
+    if (schedulesRegistered > 0 || webhooksRegistered > 0) {
+        logger.info('Boot discovery complete', {
+            photonsScanned,
+            schedulesDeclared: schedulesRegistered,
+            webhooksRegistered,
+            bases: baseCandidates.size,
+        });
+    }
+}
+/**
+ * Watch each registered base directory for `.photon.ts` create/modify
+ * events, re-extract proactive metadata on each hit, and reconcile the
+ * declared-set + webhook routes live. Closes the gap where an edit to
+ * `@scheduled` cron expressions or `@webhook` additions only reached
+ * the daemon at restart.
+ *
+ * Deduped by filename via the existing watchDebounce map (~150 ms) so
+ * editors that save-twice don't trigger two scans. Skips files that
+ * aren't `.photon.ts`.
+ */
+function watchBaseForProactiveMetadata(basePath, _isDefaultBase) {
+    if (baseDirWatchers.has(basePath))
+        return;
+    try {
+        if (!fs.existsSync(basePath))
+            return;
+    }
+    catch {
+        return;
+    }
+    // Always use the resolved basePath so hot-rescan keys match boot
+    // discovery (see the same pattern in discoverProactiveMetadataAtBoot).
+    // Previously this was `isDefaultBase ? undefined : basePath`, which
+    // produced `-::photon:method` keys on edit and left the original
+    // `<defaultBase>::photon:method` declaration stale — schedule changes
+    // in the default base were ignored until daemon restart.
+    const workingDir = basePath;
+    const onChange = (filename) => {
+        if (!filename || !filename.endsWith('.photon.ts'))
+            return;
+        // Only watch files at the base root for now. Namespace subdirs get
+        // picked up the next time the user runs a photon from there (the
+        // normal registration flow touches the bases registry).
+        const debounceKey = `base:${basePath}:${filename}`;
+        const existing = watchDebounce.get(debounceKey);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            void (async () => {
+                const currentTimer = watchDebounce.get(debounceKey);
+                if (currentTimer === timer)
+                    watchDebounce.delete(debounceKey);
+                const photonName = filename.replace(/\.photon\.ts$/, '');
+                const filePath = path.join(basePath, filename);
                 try {
-                    const content = fs.readFileSync(filePath, 'utf-8');
-                    const task = JSON.parse(content);
-                    // Skip non-IPC jobs (ScheduleProvider handles its own)
-                    if (task.source !== 'ipc')
-                        continue;
-                    // Validate required fields
-                    if (!task.id || !task.method || !task.cron || !task.photonName) {
-                        logger.warn('Skipping invalid persisted schedule', { file: filePath });
-                        skippedCount++;
-                        continue;
-                    }
-                    // TTL check: skip jobs not executed in 30+ days
-                    const lastExec = task.lastExecutionAt ? new Date(task.lastExecutionAt).getTime() : 0;
-                    const created = task.createdAt ? new Date(task.createdAt).getTime() : 0;
-                    const lastActivity = Math.max(lastExec, created);
-                    if (lastActivity > 0 && Date.now() - lastActivity > ttlMs) {
-                        logger.info('Removing expired schedule (TTL)', {
-                            jobId: task.id,
-                            lastActivity: new Date(lastActivity).toISOString(),
+                    const changed = await scanOneForProactiveMetadata(photonName, filePath, workingDir);
+                    if (changed) {
+                        // Re-sync timers so cron edits take effect immediately.
+                        syncActiveSchedulesAtBoot();
+                        publishToChannel('system:*', {
+                            event: 'schedules-changed',
+                            photon: photonName,
+                            base: basePath,
+                            timestamp: Date.now(),
+                        });
+                        logger.info('Proactive metadata updated', {
+                            photon: photonName,
+                            base: basePath,
+                            path: filePath,
                         });
-                        try {
-                            fs.unlinkSync(filePath);
-                        }
-                        catch {
-                            /* ignore */
-                        }
-                        skippedCount++;
-                        continue;
-                    }
-                    // Skip if already registered (ScheduleProvider may have loaded it)
-                    if (scheduledJobs.has(task.id))
-                        continue;
-                    const job = {
-                        id: task.id,
-                        method: task.method,
-                        args: task.args || {},
-                        cron: task.cron,
-                        runCount: task.executionCount || 0,
-                        createdAt: created || Date.now(),
-                        createdBy: task.createdBy,
-                        photonName: task.photonName,
-                        workingDir: task.workingDir,
-                    };
-                    if (scheduleJob(job)) {
-                        loadedCount++;
-                    }
-                    else {
-                        logger.warn('Failed to schedule persisted job (invalid cron?)', { jobId: task.id });
-                        skippedCount++;
                     }
                 }
                 catch (err) {
-                    logger.warn('Failed to load persisted schedule file', {
-                        file: filePath,
+                    logger.warn('Live rescan failed', {
+                        photon: photonName,
+                        base: basePath,
                         error: getErrorMessage(err),
                     });
-                    skippedCount++;
                 }
-            }
-        }
+            })();
+        }, 150);
+        timer.unref();
+        watchDebounce.set(debounceKey, timer);
+    };
+    try {
+        const watcher = safeWatchDir(basePath, (_eventType, filename) => onChange(filename));
+        baseDirWatchers.set(basePath, watcher);
     }
     catch (err) {
-        logger.warn('Failed to scan schedules directory', {
-            dir: baseDir,
+        logger.debug('Could not watch base for proactive metadata', {
+            base: basePath,
             error: getErrorMessage(err),
         });
     }
-    if (loadedCount > 0 || skippedCount > 0) {
-        logger.info('Loaded persisted schedules', { loaded: loadedCount, skipped: skippedCount });
+}
+/** Install watchers on every registered base. Safe to call multiple times. */
+function startBaseWatchers() {
+    const defaultBase = path.resolve(getDefaultContext().baseDir);
+    watchBaseForProactiveMetadata(defaultBase, true);
+    for (const b of listActiveBases()) {
+        watchBaseForProactiveMetadata(b.path, path.resolve(b.path) === defaultBase);
+    }
+}
+/**
+ * Sync declared schedules against each base's active-schedules file.
+ *
+ * Two-step scheduling: declaring `@scheduled` doesn't activate. The user
+ * must explicitly enroll a declaration via `photon ps enable`, which
+ * writes to `{PHOTON_DIR}/.data/.active-schedules.json`. On boot we read
+ * each base's active list and register cron timers only for those
+ * entries.
+ *
+ * First-boot migration: for bases that have never gone through this
+ * sync, every currently-declared `@scheduled` gets auto-enrolled so
+ * existing behavior is preserved across the upgrade. The active file
+ * records `migratedFromAutoRegister: true` so the auto-enroll is a
+ * one-time event — subsequent boots respect user-chosen enrollment.
+ */
+function syncActiveSchedulesAtBoot() {
+    const defaultBase = path.resolve(getDefaultContext().baseDir);
+    const bases = new Set([defaultBase]);
+    for (const b of listActiveBases())
+        bases.add(b.path);
+    let registered = 0;
+    let missingRefs = 0;
+    for (const basePath of bases) {
+        const file = readActiveSchedulesFile(basePath);
+        let dirty = false;
+        // One-time migration: seed the active list from the current
+        // declarations for this base so upgrade doesn't silently disable
+        // previously-auto-registered schedules.
+        if (!file.migratedFromAutoRegister) {
+            const now = new Date().toISOString();
+            for (const decl of declaredSchedules.values()) {
+                const declBase = decl.workingDir ? path.resolve(decl.workingDir) : defaultBase;
+                if (declBase !== basePath)
+                    continue;
+                const alreadyActive = file.active.some((e) => e.photon === decl.photon && e.method === decl.method);
+                if (!alreadyActive) {
+                    file.active.push({
+                        photon: decl.photon,
+                        method: decl.method,
+                        enabledAt: now,
+                        enabledBy: 'auto-migrate',
+                    });
+                    dirty = true;
+                }
+            }
+            file.migratedFromAutoRegister = true;
+            dirty = true;
+        }
+        if (dirty) {
+            try {
+                writeActiveSchedulesFile(basePath, file);
+            }
+            catch (err) {
+                logger.warn('Could not write active-schedules file', {
+                    base: basePath,
+                    error: getErrorMessage(err),
+                });
+            }
+        }
+        // Register timers for active (non-paused) entries. Keys are scoped to
+        // basePath so two PHOTON_DIRs with the same photon:method don't collide.
+        for (const entry of file.active) {
+            if (entry.paused)
+                continue;
+            const key = declaredKey(entry.photon, entry.method, basePath);
+            const decl = declaredSchedules.get(key);
+            if (!decl) {
+                missingRefs++;
+                logger.warn('Active schedule references a declaration that no longer exists', {
+                    base: basePath,
+                    photon: entry.photon,
+                    method: entry.method,
+                    hint: '`photon ps disable` to remove or add the @scheduled tag back',
+                });
+                continue;
+            }
+            if (scheduledJobs.has(key))
+                continue;
+            const ok = scheduleJob({
+                id: key,
+                method: decl.method,
+                args: {},
+                cron: decl.cron,
+                runCount: 0,
+                createdAt: Date.now(),
+                createdBy: 'active-list',
+                photonName: decl.photon,
+                workingDir: decl.workingDir,
+                photonPath: decl.photonPath,
+            });
+            if (ok)
+                registered++;
+        }
+    }
+    if (registered > 0 || missingRefs > 0) {
+        logger.info('Active schedules synced', {
+            registered,
+            declared: declaredSchedules.size,
+            missingRefs,
+        });
     }
 }
 // ════════════════════════════════════════════════════════════════════════════════
@@ -759,8 +1526,16 @@ function loadAllPersistedSchedules() {
 // ════════════════════════════════════════════════════════════════════════════════
 let webhookServer = null;
 const WEBHOOK_PORT = parseInt(process.env.PHOTON_WEBHOOK_PORT || '0');
-// Security: rate limiter for webhook endpoint
-const webhookRateLimiter = new SimpleRateLimiter(30, 60_000);
+// Security: rate limiter for webhook endpoint. Default 60/min per source IP;
+// override via PHOTON_WEBHOOK_RATE_LIMIT / PHOTON_WEBHOOK_RATE_WINDOW_MS.
+const WEBHOOK_RATE_LIMIT = Math.max(1, parseInt(process.env.PHOTON_WEBHOOK_RATE_LIMIT || '60', 10) || 60);
+const WEBHOOK_RATE_WINDOW_MS = Math.max(1_000, parseInt(process.env.PHOTON_WEBHOOK_RATE_WINDOW_MS || '60000', 10) || 60_000);
+const webhookRateLimiter = new SimpleRateLimiter(WEBHOOK_RATE_LIMIT, WEBHOOK_RATE_WINDOW_MS);
+// Optional per-source IP allowlist. When PHOTON_WEBHOOK_ALLOWED_IPS is
+// set, requests from any address outside the listed CIDRs (or exact
+// IPv6 literals) are rejected before any auth work. Empty env → allow
+// all, keeping the default unchanged.
+const WEBHOOK_ALLOWED_IPS = parseAllowlistEnv(process.env.PHOTON_WEBHOOK_ALLOWED_IPS);
 function startWebhookServer(port) {
     if (port <= 0)
         return;
@@ -774,11 +1549,29 @@ function startWebhookServer(port) {
                 res.end();
                 return;
             }
-            // Security: rate limiting
+            // Security: CIDR allowlist (runs before rate limiting so blocked
+            // addresses don't consume the per-IP budget).
             const clientKey = req.socket?.remoteAddress || 'unknown';
+            if (WEBHOOK_ALLOWED_IPS.length > 0 && !ipInAllowlist(clientKey, WEBHOOK_ALLOWED_IPS)) {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Source IP not in webhook allowlist',
+                    sourceIp: clientKey,
+                }));
+                return;
+            }
+            // Security: rate limiting
             if (!webhookRateLimiter.isAllowed(clientKey)) {
-                res.writeHead(429, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'Too many requests' }));
+                const retryAfter = Math.ceil(WEBHOOK_RATE_WINDOW_MS / 1000);
+                res.writeHead(429, {
+                    'Content-Type': 'application/json',
+                    'Retry-After': String(retryAfter),
+                });
+                res.end(JSON.stringify({
+                    error: 'Too many requests',
+                    limit: WEBHOOK_RATE_LIMIT,
+                    windowMs: WEBHOOK_RATE_WINDOW_MS,
+                }));
                 return;
             }
             // Parse URL: /webhook/{photonName}/{method}
@@ -829,29 +1622,75 @@ function startWebhookServer(port) {
                 res.end(JSON.stringify({ error: status === 413 ? 'Request body too large' : 'Invalid JSON body' }));
                 return;
             }
-            const sessionManager = sessionManagers.get(photonName);
-            if (!sessionManager) {
-                res.writeHead(503, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: `Photon '${photonName}' not initialized` }));
-                return;
-            }
-            // Resolve method from webhook route map (if routes are registered)
+            // Resolve method from webhook route map BEFORE lazy-load. In
+            // multi-base setups the same photon name may be registered in
+            // several PHOTON_DIRs; search every matching entry for one that
+            // actually exposes this route rather than picking an arbitrary
+            // first entry (which would 404 routes that only exist in a
+            // different base's copy).
             let resolvedMethod = method;
-            const routes = webhookRoutes.get(photonName);
-            if (routes && routes.size > 0) {
-                // Only allow methods that have @webhook tag
-                const mapped = routes.get(method);
-                if (!mapped) {
+            let resolvingEntry;
+            const webhookEntries = findWebhookEntriesFor(photonName);
+            const registeredEntries = webhookEntries.filter((e) => e.routes.size > 0);
+            if (registeredEntries.length > 0) {
+                const matchingEntries = registeredEntries.filter((e) => e.routes.has(method));
+                if (matchingEntries.length === 0) {
+                    const allRoutes = new Set();
+                    for (const e of registeredEntries)
+                        for (const k of e.routes.keys())
+                            allRoutes.add(k);
                     res.writeHead(404, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         error: `No webhook route '${method}' on photon '${photonName}'`,
-                        availableRoutes: [...routes.keys()],
+                        availableRoutes: [...allRoutes],
                     }));
                     return;
                 }
-                resolvedMethod = mapped;
+                if (matchingEntries.length > 1) {
+                    logger.warn('Webhook route exists in multiple PHOTON_DIRs; routing to first match', {
+                        photon: photonName,
+                        method,
+                        bases: matchingEntries.map((e) => e.workingDir ?? '-'),
+                    });
+                }
+                resolvingEntry = matchingEntries[0];
+                resolvedMethod = resolvingEntry.routes.get(method);
+            }
+            // Use the resolving entry's workingDir to pick the right file
+            // location (proactivePhotonLocations is keyed by base+photon).
+            const webhookBase = resolvingEntry?.workingDir;
+            // Scope sessionManagers lookup by (photon, webhookBase) so a webhook
+            // for base B doesn't reuse an existing base-A session when the two
+            // PHOTON_DIRs share a photon name.
+            const sessionKey = compositeKey(photonName, webhookBase);
+            let sessionManager = sessionManagers.get(sessionKey);
+            if (!sessionManager) {
+                const candidates = findLocationsFor(photonName);
+                const loc = (webhookBase && candidates.find((c) => c.workingDir === webhookBase)) ?? candidates[0];
+                if (loc) {
+                    try {
+                        sessionManager =
+                            (await getOrCreateSessionManager(photonName, loc.photonPath, loc.workingDir)) ??
+                                undefined;
+                    }
+                    catch (err) {
+                        logger.warn('Lazy-load for webhook request failed', {
+                            photon: photonName,
+                            error: getErrorMessage(err),
+                        });
+                    }
+                }
             }
-            const webhookKey = compositeKey(photonName);
+            if (!sessionManager) {
+                res.writeHead(503, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: `Photon '${photonName}' not initialized` }));
+                return;
+            }
+            // Scope the in-flight tracker to the same base the session manager
+            // is keyed by. Without webhookBase here, drain/reload logic waiting
+            // on the base-scoped key wouldn't see this execution and could
+            // hot-reload the photon mid-webhook.
+            const webhookKey = compositeKey(photonName, webhookBase);
             trackExecution(webhookKey);
             try {
                 const session = await sessionManager.getOrCreateSession('webhook', 'webhook');
@@ -971,13 +1810,55 @@ function publishToChannel(channel, message, excludeSocket) {
 // ════════════════════════════════════════════════════════════════════════════════
 async function getOrCreateSessionManager(photonName, photonPath, workingDir) {
     const key = compositeKey(photonName, workingDir);
-    let manager = sessionManagers.get(key);
-    if (manager) {
-        return manager;
+    let manager = null;
+    // Marketplace → global walk for the session manager. Name resolution is
+    // always caller's marketplace first, then `~/.photon`. This is what makes
+    // `this.call('peer.method')` from within one marketplace reach a peer
+    // that only lives in the global install — same rule the outer CLI uses.
+    const defaultBase = getDefaultContext().baseDir;
+    const resolved = resolveWithGlobalFallback(photonName, workingDir, defaultBase, (k) => sessionManagers.get(k));
+    if (resolved) {
+        if (resolved.key !== key) {
+            logger.debug('Session manager resolved via global fallback', {
+                photonName,
+                callerBase: workingDir,
+                resolvedKey: resolved.key,
+            });
+        }
+        return resolved.value;
+    }
+    // Need photonPath to initialize. Walk the path hint the same way — a
+    // globally-registered path serves a caller from any marketplace.
+    const resolvedPath = resolveWithGlobalFallback(photonName, workingDir, defaultBase, (k) => photonPaths.get(k));
+    const storedPath = resolvedPath?.value;
+    let pathToUse = photonPath || storedPath;
+    // Disk fallback. When the in-memory maps miss (peer wasn't pre-loaded
+    // or auto-registered), walk the filesystem the same way the outer CLI
+    // does: caller's marketplace first, then the daemon's default base.
+    // This closes the same-marketplace `this.call('peer.method')` gap where
+    // the caller and the peer live side-by-side on disk but the peer was
+    // never loaded by anyone, so neither in-memory map had it.
+    if (!pathToUse) {
+        if (workingDir) {
+            const localResolved = await resolvePhotonPath(photonName, workingDir);
+            if (localResolved)
+                pathToUse = localResolved;
+        }
+        if (!pathToUse && defaultBase && defaultBase !== workingDir) {
+            const globalResolved = await resolvePhotonPath(photonName, defaultBase);
+            if (globalResolved)
+                pathToUse = globalResolved;
+        }
+        if (pathToUse) {
+            // Cache at the caller's composite key so the next call hits fast.
+            photonPaths.set(key, pathToUse);
+            logger.info('Peer photon resolved via disk fallback', {
+                photonName,
+                callerBase: workingDir,
+                resolvedPath: pathToUse,
+            });
+        }
     }
-    // Need photonPath to initialize
-    const storedPath = photonPaths.get(key);
-    const pathToUse = photonPath || storedPath;
     if (!pathToUse) {
         logger.warn('Cannot initialize photon - no path provided', { photonName, key });
         return null;
@@ -1046,8 +1927,14 @@ async function getOrCreateSessionManager(photonName, photonPath, workingDir) {
             logger.info('Spawning worker thread for @worker photon', { photonName, key });
             const info = await workerManager.spawn(key, photonName, pathToUse, workingDir);
             photonPaths.set(key, pathToUse);
-            if (!photonPaths.has(photonName))
-                photonPaths.set(photonName, pathToUse);
+            // Also mirror under the bare photon name so legacy helpers
+            // (snapshotState, persistInstanceState) without a workingDir still
+            // resolve in the default-base case. `compositeKey(name, undefined)`
+            // collapses to the bare name and is branded, so this round-trips
+            // through the type system without a raw cast.
+            const legacyKey = compositeKey(photonName);
+            if (!photonPaths.has(legacyKey))
+                photonPaths.set(legacyKey, pathToUse);
             if (workingDir)
                 workingDirs.set(key, workingDir);
             watchPhotonFile(photonName, pathToUse);
@@ -1153,9 +2040,25 @@ async function getOrCreateSessionManager(photonName, photonPath, workingDir) {
         };
         sessionManagers.set(key, manager);
         photonPaths.set(key, pathToUse);
-        // Also store under bare photonName so snapshotState/persistInstanceState can find it
-        if (!photonPaths.has(photonName)) {
-            photonPaths.set(photonName, pathToUse);
+        // Legacy callers without a workingDir (snapshotState, persistInstanceState)
+        // reach this map via bare photon name. compositeKey(name, undefined)
+        // collapses to that bare name for the default base and is branded, so
+        // the mirror entry preserves the legacy lookup path type-safely.
+        const legacyKey = compositeKey(photonName);
+        if (!photonPaths.has(legacyKey)) {
+            photonPaths.set(legacyKey, pathToUse);
+        }
+        // Baseline the stat-gate for this session so subsequent dispatches can
+        // detect source edits the file watcher hasn't processed yet.
+        recordPhotonSourceStat(key, pathToUse);
+        // Record this PHOTON_DIR in the bases registry so future daemon startups
+        // can scan it for schedules and other per-base data. See
+        // docs/internals/PHOTON-DIR-AND-NAMESPACE.md §8.
+        try {
+            touchBase(workingDir || getDefaultContext().baseDir);
+        }
+        catch (err) {
+            logger.warn('Failed to update bases registry', { error: getErrorMessage(err) });
         }
         if (workingDir) {
             workingDirs.set(key, workingDir);
@@ -1179,24 +2082,117 @@ async function getOrCreateSessionManager(photonName, photonPath, workingDir) {
 }
 // Track which photons have had their metadata auto-registered
 const autoRegistered = new Set();
-// Webhook route map: photonName → Set<allowed method names>
+// Typed with WebhookRouteKey so bare-string .get() no longer compiles —
+// every access must go through webhookKey(photon, workingDir) or
+// findByPhoton(webhookRoutes, photon). This is the compile-time
+// guardrail against the cascade that hit us post-v1.22.1.
 const webhookRoutes = new Map();
+/** Composite key for the webhookRoutes map. Delegates to registry-keys.ts. */
+const webhookKey = _webhookKey;
+/** Find every webhook entry registered under `photonName` (any base). */
+function findWebhookEntriesFor(photonName) {
+    return findByPhoton(webhookRoutes, photonName);
+}
+// Keyed by `<base>::<photonName>` so multi-base discovery doesn't clobber:
+// two PHOTON_DIRs can host a photon with the same name and the webhook
+// server must be able to lazy-load each one from its own file.
+const proactivePhotonLocations = new Map();
+const locationKey = _locationKey;
+/**
+ * Find every proactive-location entry registered for this photon name.
+ * The HTTP webhook handler uses this plus the resolving webhook entry's
+ * base to pick the right file.
+ */
+function findLocationsFor(photonName) {
+    return findByPhoton(proactivePhotonLocations, photonName);
+}
+const declaredSchedules = new Map();
+/**
+ * Identity key for declared schedules and scheduled jobs. Delegates to
+ * registry-keys.ts — see that module for the key-shape rationale.
+ */
+const declaredKey = _declaredKey;
+/**
+ * Scan declaredSchedules for the declaration matching (photon, method).
+ * When an IPC caller doesn't know which PHOTON_DIR owns the schedule (the CLI
+ * hits a per-user daemon but the user may have multiple bases), search all
+ * declarations. If `preferredBase` is supplied, prefer that match. If multiple
+ * declarations match across bases, return them so the caller can surface an
+ * ambiguity error instead of silently picking one.
+ */
+function findDeclarationsFor(photon, method, preferredBase) {
+    const matches = [];
+    const preferredResolved = preferredBase ? path.resolve(preferredBase) : undefined;
+    for (const [key, decl] of declaredSchedules.entries()) {
+        if (decl.photon !== photon || decl.method !== method)
+            continue;
+        const declBase = decl.workingDir ? path.resolve(decl.workingDir) : undefined;
+        if (preferredResolved && declBase && declBase !== preferredResolved)
+            continue;
+        matches.push({ key, decl });
+    }
+    return matches;
+}
+function activeSchedulesPath(baseDir) {
+    return path.join(baseDir, '.data', '.active-schedules.json');
+}
+function readActiveSchedulesFile(baseDir) {
+    const file = activeSchedulesPath(baseDir);
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && Array.isArray(parsed.active)) {
+            return {
+                version: 1,
+                active: parsed.active.filter((e) => e &&
+                    typeof e.photon === 'string' &&
+                    typeof e.method === 'string' &&
+                    typeof e.enabledAt === 'string'),
+                migratedFromAutoRegister: !!parsed.migratedFromAutoRegister,
+            };
+        }
+    }
+    catch {
+        // Missing or malformed — treated as empty.
+    }
+    return { version: 1, active: [] };
+}
+function writeActiveSchedulesFile(baseDir, data) {
+    const file = activeSchedulesPath(baseDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ ...data, version: 1 }, null, 2));
+    fs.renameSync(tmp, file);
+}
 /**
  * Auto-register scheduled jobs and webhook routes from tool metadata.
  * Called once per photon on first session manager creation.
  */
 async function autoRegisterFromMetadata(photonName, manager) {
-    if (autoRegistered.has(photonName))
+    // Key by (photon, base) so loading photon foo from base B doesn't skip
+    // auto-registration just because foo from base A already registered.
+    // Without this, the second copy silently loses its @scheduled and
+    // @webhook metadata until daemon restart.
+    const autoKey = compositeKey(photonName, manager.loader?.baseDir);
+    if (autoRegistered.has(autoKey))
         return;
-    autoRegistered.add(photonName);
+    autoRegistered.add(autoKey);
     try {
         // Get a session to access the loaded photon's tools
         const session = await manager.getOrCreateSession('__autoregister', 'system');
         const tools = session.instance?.tools || [];
-        // Auto-register @scheduled jobs
+        // Auto-register @scheduled jobs. Use the same base-scoped key format as
+        // declaredKey so a photon enabled via `photon ps enable` doesn't end up
+        // running twice — once under the legacy `${photon}:${method}` ID and
+        // once under the new `<base>::${photon}:${method}` ID.
+        //
+        // SessionManager.getOrCreateSession() doesn't attach workingDir to the
+        // session object, so read it from the underlying loader — the same
+        // source of truth used for the per-base schedules dir below.
+        const sessionWorkingDir = manager.loader?.baseDir;
         for (const tool of tools) {
             if (tool.scheduled) {
-                const jobId = `${photonName}:${tool.name}`;
+                const jobId = declaredKey(photonName, tool.name, sessionWorkingDir);
                 if (!scheduledJobs.has(jobId)) {
                     const job = {
                         id: jobId,
@@ -1207,6 +2203,7 @@ async function autoRegisterFromMetadata(photonName, manager) {
                         createdAt: Date.now(),
                         createdBy: 'auto',
                         photonName,
+                        workingDir: sessionWorkingDir,
                     };
                     const ok = scheduleJob(job);
                     if (ok) {
@@ -1219,30 +2216,52 @@ async function autoRegisterFromMetadata(photonName, manager) {
                     }
                 }
             }
-            // Build webhook route map
+            // Build webhook route map using the base-scoped key so two
+            // PHOTON_DIRs with the same photon name don't clobber each other.
             if (tool.webhook !== undefined) {
-                let routes = webhookRoutes.get(photonName);
-                if (!routes) {
-                    routes = new Map();
-                    webhookRoutes.set(photonName, routes);
+                const wKey = webhookKey(photonName, sessionWorkingDir);
+                let entry = webhookRoutes.get(wKey);
+                if (!entry) {
+                    entry = { photon: photonName, routes: new Map(), workingDir: sessionWorkingDir };
+                    webhookRoutes.set(wKey, entry);
                 }
                 // Custom path from @webhook <path>, or method name
                 const routePath = typeof tool.webhook === 'string' ? tool.webhook : tool.name;
-                routes.set(routePath, tool.name);
+                entry.routes.set(routePath, tool.name);
             }
         }
-        if (webhookRoutes.has(photonName)) {
-            const routes = webhookRoutes.get(photonName);
+        const autoKey = webhookKey(photonName, sessionWorkingDir);
+        if (webhookRoutes.has(autoKey)) {
+            const routes = webhookRoutes.get(autoKey).routes;
             logger.info('Auto-registered webhook routes from @webhook tags', {
                 photon: photonName,
                 routes: [...routes.keys()],
             });
         }
-        // Load persisted schedule files from ~/.photon/schedules/{photonName}/
-        // These are created by this.schedule.create() at runtime.
-        const schedulesDir = path.join(process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules'), photonName.replace(/[^a-zA-Z0-9_-]/g, '_'));
-        try {
-            const scheduleFiles = fs.readdirSync(schedulesDir).filter((f) => f.endsWith('.json'));
+        // Load persisted schedule files created by this.schedule.create() at
+        // runtime. Scan the new per-base location first, then the legacy
+        // ~/.photon/schedules/ location for backwards compatibility.
+        const workingDir = manager.loader?.baseDir;
+        const schedulesDirs = [
+            resolveScheduleDir(photonName, workingDir),
+            resolveLegacyScheduleDir(photonName),
+        ];
+        for (const schedulesDir of schedulesDirs) {
+            let scheduleFiles;
+            try {
+                scheduleFiles = fs.readdirSync(schedulesDir).filter((f) => f.endsWith('.json'));
+            }
+            catch (err) {
+                // ENOENT is fine — no schedules dir means no persisted schedules here
+                if (err.code !== 'ENOENT') {
+                    logger.warn('Failed to load persisted schedules', {
+                        photon: photonName,
+                        dir: schedulesDir,
+                        error: getErrorMessage(err),
+                    });
+                }
+                continue;
+            }
             for (const file of scheduleFiles) {
                 try {
                     const content = fs.readFileSync(path.join(schedulesDir, file), 'utf-8');
@@ -1250,7 +2269,7 @@ async function autoRegisterFromMetadata(photonName, manager) {
                     if (task.status !== 'active')
                         continue;
                     const jobId = `${photonName}:sched:${task.id}`;
-                    if (scheduledJobs.has(jobId))
+                    if (scheduledJobs.has(asScheduleKey(jobId)))
                         continue;
                     const job = {
                         id: jobId,
@@ -1278,15 +2297,6 @@ async function autoRegisterFromMetadata(photonName, manager) {
                 }
             }
         }
-        catch (err) {
-            // ENOENT is fine — no schedules dir means no persisted schedules
-            if (err.code !== 'ENOENT') {
-                logger.warn('Failed to load persisted schedules', {
-                    photon: photonName,
-                    error: getErrorMessage(err),
-                });
-            }
-        }
     }
     catch (error) {
         logger.warn('Failed to auto-register metadata', {
@@ -1645,7 +2655,7 @@ async function handleRequest(request, socket) {
         const ipcJobId = dirHash
             ? `${photonName}:${dirHash}:ipc:${request.jobId}`
             : `${photonName}:ipc:${request.jobId}`;
-        const existing = scheduledJobs.get(ipcJobId);
+        const existing = scheduledJobs.get(asScheduleKey(ipcJobId));
         const job = {
             id: ipcJobId,
             method: request.method,
@@ -1672,7 +2682,9 @@ async function handleRequest(request, socket) {
     }
     // Handle job unscheduling
     if (request.type === 'unschedule') {
-        const jobId = request.jobId;
+        // IPC input: coerce at the boundary. Job IDs shipped over the protocol
+        // are already ScheduleKey-shaped (<base>::<photon>:<method>).
+        const jobId = asScheduleKey(request.jobId);
         // Try exact match first, then look for IPC-prefixed version
         let actualJobId = jobId;
         if (!scheduledJobs.has(jobId)) {
@@ -1696,11 +2708,311 @@ async function handleRequest(request, socket) {
             data: { unscheduled, jobId: actualJobId },
         };
     }
-    // Handle list jobs
+    // Handle list jobs (legacy shape — just the active cron jobs)
     if (request.type === 'list_jobs') {
         const jobs = Array.from(scheduledJobs.values());
         return { type: 'result', id: request.id, success: true, data: { jobs } };
     }
+    // `photon ps` full snapshot: active timers, declared-but-dormant schedules,
+    // webhook routes, loaded sessions. Agent-friendly (structured) and compact.
+    if (request.type === 'ps') {
+        const defaultBase = path.resolve(getDefaultContext().baseDir);
+        const active = Array.from(scheduledJobs.values()).map((j) => ({
+            id: j.id,
+            photon: j.photonName,
+            method: j.method,
+            cron: j.cron,
+            nextRun: j.nextRun ?? null,
+            lastRun: j.lastRun ?? null,
+            runCount: j.runCount,
+            photonPath: j.photonPath,
+            workingDir: j.workingDir ?? defaultBase,
+            createdBy: j.createdBy,
+        }));
+        const declared = Array.from(declaredSchedules.values()).map((d) => {
+            const k = declaredKey(d.photon, d.method, d.workingDir);
+            return {
+                key: k,
+                photon: d.photon,
+                method: d.method,
+                cron: d.cron,
+                photonPath: d.photonPath,
+                workingDir: d.workingDir ?? defaultBase,
+                active: scheduledJobs.has(k),
+            };
+        });
+        const webhooks = [];
+        for (const entry of webhookRoutes.values()) {
+            const loc = proactivePhotonLocations.get(locationKey(entry.photon, entry.workingDir));
+            const owningDir = entry.workingDir ?? loc?.workingDir ?? defaultBase;
+            for (const [route, methodName] of entry.routes.entries()) {
+                webhooks.push({
+                    photon: entry.photon,
+                    route,
+                    method: methodName,
+                    workingDir: owningDir,
+                });
+            }
+        }
+        const sessions = [];
+        for (const [key, mgr] of sessionManagers.entries()) {
+            const stored = workingDirs.get(key);
+            const photonFromKey = key.includes(':') ? key.split(':')[0] : key;
+            sessions.push({
+                photon: photonFromKey,
+                workingDir: stored ?? defaultBase,
+                key,
+                instanceCount: mgr.getSessions().length,
+            });
+        }
+        return {
+            type: 'result',
+            id: request.id,
+            success: true,
+            data: { active, declared, webhooks, sessions },
+        };
+    }
+    // Enroll a declared @scheduled method into the active list.
+    if (request.type === 'enable_schedule') {
+        const photon = request.photonName;
+        const method = request.method;
+        if (!photon || !method) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: '`enable_schedule` requires photonName and method',
+            };
+        }
+        const preferredBase = request.workingDir;
+        const matches = findDeclarationsFor(photon, method, preferredBase);
+        if (matches.length === 0) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `No @scheduled declaration found for ${photon}:${method}. ` +
+                    `Did the source file get renamed or deleted?`,
+            };
+        }
+        if (matches.length > 1) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `Ambiguous: ${photon}:${method} is declared in multiple PHOTON_DIRs ` +
+                    `(${matches.map((m) => m.decl.workingDir ?? '-').join(', ')}). ` +
+                    `Pass workingDir to target one.`,
+            };
+        }
+        const { key, decl } = matches[0];
+        const base = path.resolve(decl.workingDir || getDefaultContext().baseDir);
+        const file = readActiveSchedulesFile(base);
+        const existing = file.active.find((e) => e.photon === photon && e.method === method);
+        if (existing) {
+            if (existing.paused)
+                existing.paused = false;
+        }
+        else {
+            file.active.push({
+                photon,
+                method,
+                enabledAt: new Date().toISOString(),
+                enabledBy: request.source || 'rpc',
+            });
+        }
+        writeActiveSchedulesFile(base, file);
+        // Also record this base so daemon restarts find it.
+        try {
+            touchBase(base);
+        }
+        catch {
+            /* non-fatal */
+        }
+        if (!scheduledJobs.has(key)) {
+            scheduleJob({
+                id: key,
+                method: decl.method,
+                args: {},
+                cron: decl.cron,
+                runCount: 0,
+                createdAt: Date.now(),
+                createdBy: 'ps-enable',
+                photonName: decl.photon,
+                workingDir: decl.workingDir,
+                photonPath: decl.photonPath,
+            });
+        }
+        return {
+            type: 'result',
+            id: request.id,
+            success: true,
+            data: { photon, method, base, cron: decl.cron, status: 'active' },
+        };
+    }
+    // Remove a schedule from the active list (drops the timer and the file entry).
+    if (request.type === 'disable_schedule') {
+        const photon = request.photonName;
+        const method = request.method;
+        if (!photon || !method) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: '`disable_schedule` requires photonName and method',
+            };
+        }
+        const preferredBase = request.workingDir;
+        const matches = findDeclarationsFor(photon, method, preferredBase);
+        if (matches.length > 1) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `Ambiguous: ${photon}:${method} is declared in multiple PHOTON_DIRs ` +
+                    `(${matches.map((m) => m.decl.workingDir ?? '-').join(', ')}). ` +
+                    `Pass workingDir to target one.`,
+            };
+        }
+        const match = matches[0];
+        // Disable tolerates a missing declaration so the caller can clean up
+        // orphan active-schedule rows after the source file is deleted.
+        const base = path.resolve(match?.decl.workingDir ?? preferredBase ?? getDefaultContext().baseDir);
+        const file = readActiveSchedulesFile(base);
+        const before = file.active.length;
+        file.active = file.active.filter((e) => !(e.photon === photon && e.method === method));
+        const removed = before - file.active.length;
+        writeActiveSchedulesFile(base, file);
+        // Clear the timer if one is running. Use the declaration's key when we
+        // have it; otherwise scan to find any scheduled job for this (photon, method)
+        // that's scoped to the resolved base. unscheduleJob does the atomic
+        // clearTimeout + scheduledJobs.delete + jobTimers.delete dance; calling
+        // the three map ops manually was the class of bug that codex round 9
+        // flagged.
+        const key = match?.key ?? declaredKey(photon, method, base);
+        unscheduleJob(key);
+        // Defensive sweep: during upgrade transitions a daemon may still hold
+        // timers registered under the pre-base-scoping `${photon}:${method}` key
+        // format. Report-success-but-keep-firing is worse than a noisy sweep, so
+        // also drop any job matching this request — but only when the job is
+        // scoped to THIS base (or the legacy "no base" form). Without this check,
+        // disabling foo:bar under base X would also stop foo:bar under base Y,
+        // silently breaking the other PHOTON_DIR's timer.
+        for (const staleKey of Array.from(scheduledJobs.keys())) {
+            const job = scheduledJobs.get(staleKey);
+            if (!job)
+                continue;
+            if (job.photonName !== photon || job.method !== method)
+                continue;
+            if (staleKey === key)
+                continue; // already handled above
+            // Only sweep legacy keys (no base prefix) and keys scoped to `base`.
+            const jobBase = job.workingDir ? path.resolve(job.workingDir) : undefined;
+            if (jobBase && jobBase !== base)
+                continue;
+            unscheduleJob(staleKey);
+        }
+        return {
+            type: 'result',
+            id: request.id,
+            success: true,
+            data: { photon, method, base, removed: removed > 0, status: 'disabled' },
+        };
+    }
+    // Pause: keep the enrollment record but cancel the timer.
+    if (request.type === 'pause_schedule' || request.type === 'resume_schedule') {
+        const photon = request.photonName;
+        const method = request.method;
+        const pause = request.type === 'pause_schedule';
+        if (!photon || !method) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `\`${pause ? 'pause_schedule' : 'resume_schedule'}\` requires photonName and method`,
+            };
+        }
+        const preferredBase = request.workingDir;
+        const matches = findDeclarationsFor(photon, method, preferredBase);
+        if (matches.length > 1) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `Ambiguous: ${photon}:${method} is declared in multiple PHOTON_DIRs ` +
+                    `(${matches.map((m) => m.decl.workingDir ?? '-').join(', ')}). ` +
+                    `Pass workingDir to target one.`,
+            };
+        }
+        const match = matches[0];
+        const decl = match?.decl;
+        const base = path.resolve(decl?.workingDir ?? preferredBase ?? getDefaultContext().baseDir);
+        const key = match?.key ?? declaredKey(photon, method, base);
+        const file = readActiveSchedulesFile(base);
+        const entry = file.active.find((e) => e.photon === photon && e.method === method);
+        if (!entry) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `No active enrollment for ${photon}:${method} under ${base}. Enable it first.`,
+            };
+        }
+        entry.paused = pause;
+        writeActiveSchedulesFile(base, file);
+        if (pause) {
+            unscheduleJob(key);
+        }
+        else if (decl) {
+            scheduleJob({
+                id: key,
+                method: decl.method,
+                args: {},
+                cron: decl.cron,
+                runCount: 0,
+                createdAt: Date.now(),
+                createdBy: 'ps-resume',
+                photonName: decl.photon,
+                workingDir: decl.workingDir,
+                photonPath: decl.photonPath,
+            });
+        }
+        return {
+            type: 'result',
+            id: request.id,
+            success: true,
+            data: { photon, method, base, status: pause ? 'paused' : 'active' },
+        };
+    }
+    // Return recent firings recorded by recordExecution() — scoped to one
+    // photon:method, newest first, filterable by time window.
+    if (request.type === 'get_execution_history') {
+        const photon = request.photonName;
+        const method = request.method;
+        if (!photon || !method) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: '`get_execution_history` requires photonName and method',
+            };
+        }
+        // Prefer the caller-supplied workingDir; fall back to the declaration's
+        // base; finally to the default base. Multiple PHOTON_DIRs can legitimately
+        // carry the same photon:method — if workingDir wasn't provided and there's
+        // more than one declaration, return an ambiguity error so the caller picks.
+        const preferredBase = request.workingDir;
+        const historyMatches = findDeclarationsFor(photon, method, preferredBase);
+        if (historyMatches.length > 1 && !preferredBase) {
+            return {
+                type: 'error',
+                id: request.id,
+                error: `Ambiguous: ${photon}:${method} is declared in multiple PHOTON_DIRs ` +
+                    `(${historyMatches.map((m) => m.decl.workingDir ?? '-').join(', ')}). ` +
+                    `Pass workingDir to target one.`,
+            };
+        }
+        const decl = historyMatches[0]?.decl;
+        const workingDir = preferredBase || decl?.workingDir || getDefaultContext().baseDir;
+        const entries = readExecutionHistory(photon, { method, limit: request.limit, sinceTs: request.sinceTs }, workingDir);
+        return {
+            type: 'result',
+            id: request.id,
+            success: true,
+            data: { photon, method, entries },
+        };
+    }
     if (request.type === 'get_circuit_health') {
         // Aggregate circuit breaker states from all loaded photon loaders
         const circuits = {};
@@ -1818,6 +3130,11 @@ async function handleRequest(request, socket) {
                 error: `Cannot initialize photon '${photonName}'. Provide photonPath in request.`,
             };
         }
+        // Stat-gate: if the source file has changed since we last loaded it,
+        // synchronously reload before dispatching. Closes the race window where
+        // a request arrives between a file write and the watcher's debounce.
+        const dispatchPhotonPath = request.photonPath || photonPaths.get(cmdKey);
+        await statGate(cmdKey, photonName, dispatchPhotonPath, request.workingDir);
         try {
             const session = await sessionManager.getOrCreateSession(request.sessionId, request.clientType);
             // ── Auto-recover from instance drift ─────────────────────────
@@ -2179,6 +3496,9 @@ const stateKeysCache = new Map();
  * State params: non-primitive with default on @stateful photon.
  */
 async function getStateKeys(photonName, photonPath) {
+    // stateKeysCache is photon-code-derived (independent of base), so it's
+    // safe to use bare photonName as the cache key regardless of which
+    // PHOTON_DIR loaded the file — all copies produce the same state schema.
     if (stateKeysCache.has(photonName)) {
         return stateKeysCache.get(photonName);
     }
@@ -2208,8 +3528,10 @@ async function getStateKeys(photonName, photonPath) {
  * Returns null for non-stateful photons (no state keys).
  * Used for JSON Patch diffing (pre/post execution).
  */
-async function snapshotState(instance, photonName) {
-    const photonPath = photonPaths.get(photonName);
+async function snapshotState(instance, photonName, workingDir) {
+    // Composite key collapses to bare photon name for the default base, so
+    // pre-multi-base callers that passed just photonName still resolve.
+    const photonPath = photonPaths.get(compositeKey(photonName, workingDir));
     if (!photonPath)
         return null;
     const keys = await getStateKeys(photonName, photonPath);
@@ -2238,7 +3560,7 @@ async function snapshotState(instance, photonName) {
  */
 async function persistInstanceState(instance, photonName, instanceName, workingDir) {
     try {
-        const photonPath = photonPaths.get(photonName);
+        const photonPath = photonPaths.get(compositeKey(photonName, workingDir));
         if (!photonPath)
             return;
         const keys = await getStateKeys(photonName, photonPath);
@@ -2284,13 +3606,14 @@ async function persistInstanceState(instance, photonName, instanceName, workingD
 const eventLogSeq = new Map();
 const EVENT_LOG_MAX_SIZE = parseInt(process.env.PHOTON_EVENT_LOG_MAX_SIZE || '', 10) || 10 * 1024 * 1024; // 10MB default
 /**
- * Get the event log path for a photon instance.
- * Co-located with state file: ~/.photon/state/{photon}/{instance}.log
+ * Get the event log path for a photon instance under the Option B layout:
+ * `{PHOTON_DIR}/.data/{photon}/state/{instance}/state.log`. Delegates to
+ * the canonical photon-core helper so all callers land on the same path.
+ * Namespace is threaded through as empty (flat root) — sub-namespace log
+ * routing lands as part of the later namespace-aware instance work.
  */
 function getInstanceLogPath(photonName, instanceName, baseDir) {
-    const name = instanceName || 'default';
-    const dir = baseDir || getDefaultContext().baseDir;
-    return path.join(dir, 'state', photonName, `${name}.log`);
+    return getPhotonStateLogPath('', photonName, instanceName || 'default', baseDir || getDefaultContext().baseDir);
 }
 /**
  * Append an event entry to the JSONL event log.
@@ -2362,10 +3685,10 @@ function pushUndoEntry(photonName, instance, entry) {
  * Apply a JSON Patch to a live photon instance's state.
  * Snapshots state as plain JSON, applies patch, then rehydrates instance properties.
  */
-async function applyPatchToInstance(instance, photonName, ops) {
+async function applyPatchToInstance(instance, photonName, ops, workingDir) {
     // Use the already-imported fastJsonPatch module
     const applyPatch = fastJsonPatch.applyPatch.bind(fastJsonPatch);
-    const photonPath = photonPaths.get(photonName);
+    const photonPath = photonPaths.get(compositeKey(photonName, workingDir));
     if (!photonPath)
         return;
     const keys = await getStateKeys(photonName, photonPath);
@@ -2998,18 +4321,13 @@ async function doReloadPhoton(photonName, newPhotonPath, workingDir, key) {
                 // This covers in-memory state (maps, arrays, flags, caches) without requiring
                 // every photon to manually copy fields in onInitialize. Photons only need
                 // onInitialize for non-copyable resources (sockets, timers, DB connections).
+                //
+                // Exception: loader-injected settings fields carry the OLD schema/backing.
+                // The fresh instance has already been wired with the new schema and reloaded
+                // the persisted values from disk — overwriting them here keeps the daemon
+                // serving the pre-reload settings shape until a full restart.
                 if (oldMcp?.instance && newMcp?.instance && typeof oldMcp.instance === 'object') {
-                    for (const key of Object.keys(oldMcp.instance)) {
-                        const value = oldMcp.instance[key];
-                        if (typeof value !== 'function' && key !== 'constructor') {
-                            try {
-                                newMcp.instance[key] = value;
-                            }
-                            catch {
-                                // Some properties may be read-only (e.g. settings proxy)
-                            }
-                        }
-                    }
+                    transferHotReloadState(oldMcp.instance, newMcp.instance);
                 }
                 // Call onInitialize on the new instance with hot-reload context.
                 // Always passes oldInstance so lifecycle photons can transfer non-copyable
@@ -3044,6 +4362,9 @@ async function doReloadPhoton(photonName, newPhotonPath, workingDir, key) {
             timestamp: Date.now(),
             sessionsUpdated: updatedCount,
         });
+        // Refresh the stat-gate baseline so the next dispatch's stat check
+        // sees the file it just loaded (not the stat from before this reload).
+        recordPhotonSourceStat(key, newPhotonPath);
         logger.info('Photon reloaded successfully', { photonName, sessionsUpdated: updatedCount });
         return { success: true, sessionsUpdated: updatedCount };
     }
@@ -3188,7 +4509,7 @@ function startupWatchPhotons() {
             continue;
         const photonName = entry.name.slice(0, -ext.length);
         const photonPath = path.join(photonDir, entry.name);
-        photonPaths.set(photonName, photonPath);
+        photonPaths.set(compositeKey(photonName), photonPath);
         watchPhotonFile(photonName, photonPath);
     }
     logger.info('Startup watch registered', { count: fileWatchers.size, dir: photonDir });
@@ -3260,19 +4581,21 @@ function startupWatchPhotons() {
                 return;
             const photonName = filename.slice(0, -ext.length);
             const filePath = path.join(photonDir, filename);
+            const photonKey = compositeKey(photonName);
             // New file added — register and watch it
-            if (!photonPaths.has(photonName) && fs.existsSync(filePath)) {
-                photonPaths.set(photonName, filePath);
+            if (!photonPaths.has(photonKey) && fs.existsSync(filePath)) {
+                photonPaths.set(photonKey, filePath);
                 watchPhotonFile(photonName, filePath);
                 logger.info('Auto-discovered new photon', { photonName, path: filePath });
             }
             // File removed — clean up
-            if (photonPaths.has(photonName) && !fs.existsSync(filePath)) {
-                photonPaths.delete(photonName);
-                const watcher = fileWatchers.get(photonName);
+            if (photonPaths.has(photonKey) && !fs.existsSync(filePath)) {
+                photonPaths.delete(photonKey);
+                // fileWatchers is keyed by file path, not composite key
+                const watcher = fileWatchers.get(filePath);
                 if (watcher) {
                     watcher.close();
-                    fileWatchers.delete(photonName);
+                    fileWatchers.delete(filePath);
                 }
                 logger.info('Photon file removed', { photonName, path: filePath });
             }
@@ -3552,7 +4875,19 @@ void (async () => {
     await claimExclusiveOwnership();
     startupWatchPhotons();
     startServer();
+    migrateLegacyIpcSchedules();
     loadAllPersistedSchedules();
+    void (async () => {
+        await discoverProactiveMetadataAtBoot();
+        syncActiveSchedulesAtBoot();
+        startBaseWatchers();
+        try {
+            sweepExecutionHistoryBases(listActiveBases().map((b) => b.path));
+        }
+        catch (err) {
+            logger.debug('Execution-history sweep skipped', { error: getErrorMessage(err) });
+        }
+    })();
     startWebhookServer(WEBHOOK_PORT);
     startIdleTimer();
     startHealthMonitor();