ultravisor 1.0.17 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.17",
+    "version": "1.0.19",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -34,7 +34,7 @@
         "pict": "^1.0.361",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
-        "ultravisor-beacon": "^0.0.8",
+        "ultravisor-beacon": "^0.0.9",
         "ws": "^8.20.0"
     },
     "devDependencies": {

package/source/cli/Ultravisor-CLIProgram.cjs

@@ -116,6 +116,34 @@ if (_LogFilePath)
 	console.log(`[Ultravisor] Logging to file: ${_LogFilePath}`);
 }
 
+// Apply LogNoisiness from RETOLD_LOG_NOISINESS env var. Pict-style log
+// noisiness is a 0-5 scale where 0 is silent (production default) and 5 shows
+// everything. Diagnostic log statements throughout Ultravisor (especially the
+// shared-fs reachability auto-detect path and the platform tasks) are gated
+// with `if (this.fable.LogNoisiness >= N)` so they're free at level 0 and
+// explosively detailed at level 4-5.
+//
+// Useful values:
+//   1 — high-level decisions (auto-detected shared-fs peer X)
+//   2 — entry points and decisions in shared-fs / dispatch paths
+//   3 — per-candidate iteration in reachability
+//   4 — per-mount comparison details
+//   5 — everything
+//
+// In stack-mode the launcher inherits process.env into the child Ultravisor
+// process automatically, so setting RETOLD_LOG_NOISINESS once on the host
+// (or in the docker-compose `environment:` block) lights up both processes.
+let _LogNoisiness = parseInt(process.env.RETOLD_LOG_NOISINESS, 10);
+if (!isNaN(_LogNoisiness) && _LogNoisiness > 0)
+{
+	_Ultravisor_Pict.LogNoisiness = _LogNoisiness;
+	if (_Ultravisor_Pict.fable && _Ultravisor_Pict.fable !== _Ultravisor_Pict)
+	{
+		_Ultravisor_Pict.fable.LogNoisiness = _LogNoisiness;
+	}
+	console.log(`[Ultravisor] LogNoisiness=${_LogNoisiness} (verbose diagnostics enabled).`);
+}
+
 // If a config file override was passed via --config / -c, apply it on top of the gathered config
 if (_ConfigFileOverride)
 {

package/source/services/Ultravisor-Beacon-Coordinator.cjs

@@ -231,6 +231,16 @@ class UltravisorBeaconCoordinator extends libPictService
 			{
 				tmpExistingBeacon.BindAddresses = pBeaconInfo.BindAddresses;
 			}
+			// Refresh shared-fs identity on reconnect — host id can change between
+			// container restarts and a reconnecting beacon may have new mounts.
+			if (typeof pBeaconInfo.HostID === 'string' && pBeaconInfo.HostID.length > 0)
+			{
+				tmpExistingBeacon.HostID = pBeaconInfo.HostID;
+			}
+			if (Array.isArray(pBeaconInfo.SharedMounts))
+			{
+				tmpExistingBeacon.SharedMounts = pBeaconInfo.SharedMounts;
+			}
 
 			this.log.info(`BeaconCoordinator: reconnected beacon [${tmpExistingBeacon.BeaconID}] "${tmpName}" with session [${tmpExistingBeacon.SessionID}].`);
 
@@ -272,6 +282,11 @@ class UltravisorBeaconCoordinator extends libPictService
 			Tags: pBeaconInfo.Tags || {},
 			Contexts: pBeaconInfo.Contexts || {},
 			BindAddresses: Array.isArray(pBeaconInfo.BindAddresses) ? pBeaconInfo.BindAddresses : [],
+			// Shared-fs identity. Both fields are optional for backwards compatibility:
+			// older beacons that don't send them just get null/[] and the shared-fs
+			// strategy is silently skipped for them.
+			HostID: (typeof pBeaconInfo.HostID === 'string' && pBeaconInfo.HostID.length > 0) ? pBeaconInfo.HostID : null,
+			SharedMounts: Array.isArray(pBeaconInfo.SharedMounts) ? pBeaconInfo.SharedMounts : [],
 			RegisteredAt: new Date().toISOString()
 		};
 

package/source/services/Ultravisor-Beacon-Reachability.cjs

@@ -362,9 +362,17 @@ class UltravisorBeaconReachability extends libPictService
 	 * Determine the transfer strategy between a source beacon (file
 	 * owner) and a requesting beacon (the one that needs the file).
 	 *
+	 * Strategy ordering (most efficient first):
+	 *   local      — same beacon, no transport at all
+	 *   shared-fs  — different beacons but on the same host with overlapping
+	 *                filesystem mounts, so the requesting beacon can read the
+	 *                source's file path directly with no copy
+	 *   direct     — HTTP fetch from the source beacon's bind address
+	 *   proxy      — HTTP fetch via the coordinator
+	 *
 	 * @param {string} pSourceBeaconID - Beacon that owns the resource
 	 * @param {string} pRequestingBeaconID - Beacon that wants the resource
-	 * @returns {object} { Strategy, DirectURL }
+	 * @returns {object} { Strategy, DirectURL, SharedMountRoot? }
 	 */
 	resolveStrategy(pSourceBeaconID, pRequestingBeaconID)
 	{
@@ -386,6 +394,28 @@ class UltravisorBeaconReachability extends libPictService
 			return { Strategy: 'proxy', DirectURL: '' };
 		}
 
+		// Shared-fs detection — check whether both beacons live on the same host
+		// AND advertise at least one shared filesystem mount in common. When they
+		// do, the requesting beacon can read the source file directly from the
+		// shared mount without an HTTP transfer.
+		let tmpRequestingBeacon = tmpCoordinator.getBeacon(pRequestingBeaconID);
+		if (tmpRequestingBeacon
+			&& tmpSourceBeacon.HostID
+			&& tmpRequestingBeacon.HostID
+			&& tmpSourceBeacon.HostID === tmpRequestingBeacon.HostID)
+		{
+			let tmpSharedMount = this._findSharedMount(
+				tmpSourceBeacon.SharedMounts, tmpRequestingBeacon.SharedMounts);
+			if (tmpSharedMount)
+			{
+				return {
+					Strategy: 'shared-fs',
+					DirectURL: '',
+					SharedMountRoot: tmpSharedMount.Root
+				};
+			}
+		}
+
 		// Check matrix
 		let tmpEntry = this.getReachability(pRequestingBeaconID, pSourceBeaconID);
 
@@ -398,6 +428,181 @@ class UltravisorBeaconReachability extends libPictService
 		// unreachable or untested — fall back to proxy
 		return { Strategy: 'proxy', DirectURL: '' };
 	}
+
+	/**
+	 * Find the first MountID that appears in both beacons' SharedMounts arrays.
+	 *
+	 * The MountID is derived from `stat.dev` + the resolved root path on the
+	 * beacon side, so two beacons that bind-mount the same host directory get
+	 * the same ID, while two unrelated /media directories on different machines
+	 * (or in different containers without shared mounts) get different IDs.
+	 *
+	 * @param {Array} pSourceMounts - SharedMounts reported by the source beacon
+	 * @param {Array} pRequestingMounts - SharedMounts reported by the requester
+	 * @returns {object|null} The matching mount entry from the source beacon,
+	 *                        or null if no overlap exists
+	 */
+	_findSharedMount(pSourceMounts, pRequestingMounts)
+	{
+		if (!Array.isArray(pSourceMounts) || pSourceMounts.length === 0)
+		{
+			return null;
+		}
+		if (!Array.isArray(pRequestingMounts) || pRequestingMounts.length === 0)
+		{
+			return null;
+		}
+		for (let i = 0; i < pSourceMounts.length; i++)
+		{
+			let tmpSrc = pSourceMounts[i];
+			if (!tmpSrc || !tmpSrc.MountID)
+			{
+				continue;
+			}
+			for (let j = 0; j < pRequestingMounts.length; j++)
+			{
+				let tmpReq = pRequestingMounts[j];
+				if (!tmpReq || !tmpReq.MountID)
+				{
+					continue;
+				}
+				if (tmpSrc.MountID === tmpReq.MountID)
+				{
+					return tmpSrc;
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Walk all online beacons looking for one that shares a filesystem with
+	 * the given source beacon. Returns the first peer that:
+	 *   1. is not the source beacon itself
+	 *   2. has the same HostID as the source
+	 *   3. has at least one MountID overlap with the source
+	 *
+	 * This is used by the resolve-address task to auto-detect when a shared-fs
+	 * fast path is available even when the caller did not explicitly identify
+	 * a "requesting beacon". The typical case: retold-remote dispatches a media
+	 * operation, the file lives on retold-remote, and orator-conversion (which
+	 * will eventually consume the file) runs in the same process / on the same
+	 * host with the same content mount. The auto-detection finds orator-conversion
+	 * as a peer of retold-remote and reports the shared-fs strategy so the
+	 * file-transfer task can short-circuit.
+	 *
+	 * Diagnostic logging is gated by Fable.LogNoisiness (set via the
+	 * RETOLD_LOG_NOISINESS env var, 0-5):
+	 *   >= 2: log entry, source beacon summary, final decision
+	 *   >= 3: per-candidate iteration with rejection reasons
+	 *   >= 4: per-mount comparison details
+	 *
+	 * @param {string} pSourceBeaconID
+	 * @returns {object|null} { Peer, Mount } or null if no shared-fs peer exists
+	 */
+	findSharedFsPeer(pSourceBeaconID)
+	{
+		let tmpNoisy = (this.fable && this.fable.LogNoisiness) || 0;
+
+		let tmpCoordinator = this._getService('UltravisorBeaconCoordinator');
+		if (!tmpCoordinator)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): no UltravisorBeaconCoordinator service registered, returning null.`);
+			}
+			return null;
+		}
+
+		let tmpSource = tmpCoordinator.getBeacon(pSourceBeaconID);
+		if (!tmpSource)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon not in coordinator registry, returning null.`);
+			}
+			return null;
+		}
+		if (!tmpSource.HostID)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon has no HostID (legacy beacon), returning null.`);
+			}
+			return null;
+		}
+		if (!Array.isArray(tmpSource.SharedMounts) || tmpSource.SharedMounts.length === 0)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon advertises no SharedMounts, returning null.`);
+			}
+			return null;
+		}
+
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source HostID=${tmpSource.HostID}, ${tmpSource.SharedMounts.length} mount(s)=${JSON.stringify(tmpSource.SharedMounts.map((m) => m.MountID))}`);
+		}
+
+		let tmpAllBeacons = tmpCoordinator.listBeacons();
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): scanning ${tmpAllBeacons.length} registered beacon(s) for shared-fs peers...`);
+		}
+
+		for (let i = 0; i < tmpAllBeacons.length; i++)
+		{
+			let tmpPeer = tmpAllBeacons[i];
+			if (!tmpPeer || tmpPeer.BeaconID === pSourceBeaconID)
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer ? tmpPeer.BeaconID : '(null)'}]: ${tmpPeer ? 'self' : 'null entry'}`);
+				}
+				continue;
+			}
+			if (tmpPeer.Status && tmpPeer.Status !== 'Online')
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: status=${tmpPeer.Status} (not Online)`);
+				}
+				continue;
+			}
+			if (!tmpPeer.HostID || tmpPeer.HostID !== tmpSource.HostID)
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: HostID=${tmpPeer.HostID || '(none)'} != source ${tmpSource.HostID}`);
+				}
+				continue;
+			}
+			if (tmpNoisy >= 4)
+			{
+				this.log.info(`[Reachability]   compare mounts for [${tmpPeer.BeaconID}]: source=${JSON.stringify(tmpSource.SharedMounts.map((m) => m.MountID))} vs peer=${JSON.stringify((tmpPeer.SharedMounts || []).map((m) => m.MountID))}`);
+			}
+			let tmpSharedMount = this._findSharedMount(tmpSource.SharedMounts, tmpPeer.SharedMounts);
+			if (tmpSharedMount)
+			{
+				if (tmpNoisy >= 2)
+				{
+					this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): MATCH peer=[${tmpPeer.BeaconID}] mount=[${tmpSharedMount.MountID}] root=${tmpSharedMount.Root}`);
+				}
+				return { Peer: tmpPeer, Mount: tmpSharedMount };
+			}
+			if (tmpNoisy >= 3)
+			{
+				this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: same HostID but no overlapping MountID`);
+			}
+		}
+
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): no shared-fs peer found among ${tmpAllBeacons.length} beacon(s).`);
+		}
+		return null;
+	}
 }
 
 module.exports = UltravisorBeaconReachability;

package/source/services/tasks/platform/Ultravisor-TaskConfigs-Platform.cjs

@@ -25,6 +25,18 @@ function _getService(pTask, pTypeName)
 		: null;
 }
 
+/**
+ * Get the LogNoisiness level (0-5) from the Fable instance attached to a task.
+ * Used to gate verbose diagnostic logging in the platform tasks. The user
+ * controls this via the RETOLD_LOG_NOISINESS environment variable, which the
+ * stack launcher applies to both the retold-remote Fable and the Ultravisor
+ * Pict instance at startup.
+ */
+function _getNoisiness(pTask)
+{
+	return (pTask && pTask.fable && pTask.fable.LogNoisiness) || 0;
+}
+
 
 module.exports =
 [
@@ -60,7 +72,7 @@ module.exports =
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { URL: '', BeaconID: '', BeaconName: '', Context: '', Path: '', Filename: '' },
+					Outputs: { URL: '', BeaconID: '', BeaconName: '', Context: '', Path: '', Filename: '', LocalPath: '' },
 					Log: [`Resolve Address: could not resolve "${tmpAddress}". Beacon may be offline or context not registered.`]
 				});
 			}
@@ -74,7 +86,8 @@ module.exports =
 				Filename: tmpResolved.Filename,
 				Strategy: 'direct',
 				DirectURL: '',
-				ProxyURL: ''
+				ProxyURL: '',
+				LocalPath: ''
 			};
 
 			// Helper: build a full URL from a beacon's bind address + context path + resource path
@@ -105,29 +118,115 @@ module.exports =
 				return pDirectBaseURL.replace(/\/$/, '') + tmpContextPath + tmpEncodedPath;
 			};
 
+			// Helper: compute the absolute path on the source beacon's filesystem
+			// for the resolved resource. Returns null if the source beacon does
+			// not have a BasePath registered for this context.
+			let _computeSharedFsLocalPath = function ()
+			{
+				let tmpSourceBeacon = tmpCoordinator.getBeacon(tmpResolved.BeaconID);
+				let tmpCtx = tmpSourceBeacon && tmpSourceBeacon.Contexts
+					? tmpSourceBeacon.Contexts[tmpResolved.Context]
+					: null;
+				if (tmpCtx && tmpCtx.BasePath)
+				{
+					return libPath.join(tmpCtx.BasePath, tmpResolved.Path);
+				}
+				return null;
+			};
+
+			let tmpReachability = _getService(pTask, 'UltravisorBeaconReachability');
+			let tmpNoisy = _getNoisiness(pTask);
+
+			if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[ResolveAddress] entry: address=${tmpAddress} sourceBeacon=${tmpResolved.BeaconID} requestingBeacon=${pResolvedSettings.RequestingBeaconID || '(none)'} reachability=${tmpReachability ? 'present' : 'missing'}`);
+			}
+
 			// Resolve transfer strategy when a requesting beacon is specified
 			let tmpRequestingBeaconID = pResolvedSettings.RequestingBeaconID;
-			if (tmpRequestingBeaconID)
+			if (tmpRequestingBeaconID && tmpReachability)
 			{
-				let tmpReachability = _getService(pTask, 'UltravisorBeaconReachability');
-				if (tmpReachability)
+				if (tmpNoisy >= 2)
 				{
-					let tmpStrategyResult = tmpReachability.resolveStrategy(tmpResolved.BeaconID, tmpRequestingBeaconID);
-					tmpOutputs.Strategy = tmpStrategyResult.Strategy;
+					pTask.log.info(`[ResolveAddress] explicit RequestingBeaconID=${tmpRequestingBeaconID} provided — calling resolveStrategy directly.`);
+				}
+				let tmpStrategyResult = tmpReachability.resolveStrategy(tmpResolved.BeaconID, tmpRequestingBeaconID);
+				tmpOutputs.Strategy = tmpStrategyResult.Strategy;
 
-					if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
+				if (tmpStrategyResult.Strategy === 'shared-fs')
+				{
+					// Both beacons see the same filesystem mount.  Look up the
+					// source beacon's context BasePath and join it with the inner
+					// resource path to get an absolute path that's also valid on
+					// the requesting beacon (because they share the mount).
+					let tmpAbsPath = _computeSharedFsLocalPath();
+					if (tmpAbsPath)
+					{
+						tmpOutputs.LocalPath = tmpAbsPath;
+						// URL is intentionally left as the original (relative) URL
+						// — file-transfer will see LocalPath and short-circuit, so
+						// the URL is never actually fetched.
+					}
+					else
+					{
+						// No BasePath available — fall back to direct so the
+						// transfer still works via HTTP.
+						pTask.log.warn(`Resolve Address: shared-fs strategy chosen but no BasePath available for context [${tmpResolved.Context}] on beacon [${tmpResolved.BeaconID}], falling back to direct.`);
+						tmpOutputs.Strategy = 'direct';
+					}
+				}
+				else if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
+				{
+					tmpOutputs.DirectURL = _buildDirectURL(tmpStrategyResult.DirectURL);
+					tmpOutputs.URL = tmpOutputs.DirectURL;
+				}
+				else if (tmpStrategyResult.Strategy === 'proxy')
+				{
+					// Proxy URL: Ultravisor's own endpoint serves the file
+					tmpOutputs.ProxyURL = tmpResolved.URL;
+					tmpOutputs.URL = tmpResolved.URL;
+				}
+				// 'local' strategy: URL stays as the context BaseURL (same host)
+			}
+			else if (tmpReachability)
+			{
+				// Auto-detect a shared-fs peer when no RequestingBeaconID was passed.
+				// This is the common case for retold-remote: it dispatches a media
+				// operation, the file lives on the retold-remote beacon, and an
+				// orator-conversion beacon on the same host shares the mount. The
+				// auto-detection finds the orator-conversion peer and lets us
+				// short-circuit the file-transfer entirely.
+				if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[ResolveAddress] no RequestingBeaconID — entering auto-detect path for source ${tmpResolved.BeaconID}`);
+				}
+				let tmpPeerInfo = tmpReachability.findSharedFsPeer(tmpResolved.BeaconID);
+				if (tmpPeerInfo)
+				{
+					let tmpAbsPath = _computeSharedFsLocalPath();
+					if (tmpAbsPath)
 					{
-						tmpOutputs.DirectURL = _buildDirectURL(tmpStrategyResult.DirectURL);
-						tmpOutputs.URL = tmpOutputs.DirectURL;
+						tmpOutputs.Strategy = 'shared-fs';
+						tmpOutputs.LocalPath = tmpAbsPath;
+						pTask.log.info(`Resolve Address: auto-detected shared-fs peer [${tmpPeerInfo.Peer.BeaconID}] for source [${tmpResolved.BeaconID}] via mount [${tmpPeerInfo.Mount.MountID}].`);
+						if (tmpNoisy >= 2)
+						{
+							pTask.log.info(`[ResolveAddress] auto-detect SUCCESS: LocalPath=${tmpAbsPath} (peer=${tmpPeerInfo.Peer.BeaconID}, mount=${tmpPeerInfo.Mount.MountID})`);
+						}
 					}
-					else if (tmpStrategyResult.Strategy === 'proxy')
+					else if (tmpNoisy >= 2)
 					{
-						// Proxy URL: Ultravisor's own endpoint serves the file
-						tmpOutputs.ProxyURL = tmpResolved.URL;
-						tmpOutputs.URL = tmpResolved.URL;
+						pTask.log.info(`[ResolveAddress] auto-detect found peer [${tmpPeerInfo.Peer.BeaconID}] but source beacon has no BasePath for context [${tmpResolved.Context}] — cannot use shared-fs.`);
 					}
-					// 'local' strategy: URL stays as the context BaseURL (same host)
 				}
+				else if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[ResolveAddress] auto-detect found NO shared-fs peer for source ${tmpResolved.BeaconID} — falling through to default direct/proxy strategy.`);
+				}
+			}
+			else if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[ResolveAddress] reachability service not available — skipping auto-detect, default strategy will be used.`);
 			}
 
 			// If the URL is still relative (no protocol), use the beacon's first
@@ -158,19 +257,26 @@ module.exports =
 				tmpStateWrites[pResolvedSettings.Destination] = tmpOutputs;
 			}
 
-			pTask.log.info(`Resolve Address: ${tmpAddress} → ${tmpOutputs.URL} [${tmpOutputs.Strategy}] (beacon: ${tmpResolved.BeaconName})`);
+			let tmpResolvedDest = tmpOutputs.LocalPath || tmpOutputs.URL;
+			pTask.log.info(`Resolve Address: ${tmpAddress} → ${tmpResolvedDest} [${tmpOutputs.Strategy}] (beacon: ${tmpResolved.BeaconName})`);
+
+			let tmpLogLines = [
+				`Resolved: ${tmpAddress}`,
+				`URL: ${tmpOutputs.URL}`,
+				`Strategy: ${tmpOutputs.Strategy}`,
+				`Beacon: ${tmpResolved.BeaconName} (${tmpResolved.BeaconID})`,
+				`Context: ${tmpResolved.Context}, Path: ${tmpResolved.Path}`
+			];
+			if (tmpOutputs.LocalPath)
+			{
+				tmpLogLines.push(`LocalPath: ${tmpOutputs.LocalPath} (shared filesystem — no transfer needed)`);
+			}
 
 			return fCallback(null, {
 				EventToFire: 'Complete',
 				Outputs: tmpOutputs,
 				StateWrites: tmpStateWrites,
-				Log: [
-					`Resolved: ${tmpAddress}`,
-					`URL: ${tmpOutputs.URL}`,
-					`Strategy: ${tmpOutputs.Strategy}`,
-					`Beacon: ${tmpResolved.BeaconName} (${tmpResolved.BeaconID})`,
-					`Context: ${tmpResolved.Context}, Path: ${tmpResolved.Path}`
-				]
+				Log: tmpLogLines
 			});
 		}
 	},
@@ -182,13 +288,70 @@ module.exports =
 		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
 		{
 			let tmpSourceURL = pResolvedSettings.SourceURL;
+			let tmpSourceLocalPath = pResolvedSettings.SourceLocalPath;
 			let tmpFilename = pResolvedSettings.Filename;
+			let tmpNoisy = _getNoisiness(pTask);
+
+			if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[FileTransfer] entry: SourceURL=${tmpSourceURL ? tmpSourceURL.substring(0, 80) : '(none)'} SourceLocalPath=${tmpSourceLocalPath || '(none)'} Filename=${tmpFilename || '(none)'}`);
+			}
+
+			// Shared-filesystem fast path: if the source beacon and the requesting
+			// beacon both report the same MountID, resolve-address will populate
+			// SourceLocalPath with the absolute on-disk path.  Both beacons see the
+			// same file at the same path because they share the mount, so we hand
+			// it back as the LocalPath without copying anything.  This is the
+			// difference between "instant" and "374 MB download to staging" on a
+			// stack-mode deployment where retold-remote and orator-conversion live
+			// in the same container.
+			if (tmpSourceLocalPath)
+			{
+				if (libFS.existsSync(tmpSourceLocalPath))
+				{
+					let tmpStat;
+					try
+					{
+						tmpStat = libFS.statSync(tmpSourceLocalPath);
+					}
+					catch (pStatError)
+					{
+						tmpStat = null;
+					}
+					pTask.log.info(`File Transfer: shared-fs hit, using ${tmpSourceLocalPath} directly (${tmpStat ? tmpStat.size : '?'} bytes, no copy).`);
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: {
+							LocalPath: tmpSourceLocalPath,
+							BytesTransferred: 0,
+							DurationMs: 0,
+							Strategy: 'shared-fs'
+						},
+						Log: [
+							`Shared filesystem detected — no transfer needed.`,
+							`Source path: ${tmpSourceLocalPath}`,
+							`Bytes transferred: 0 (zero-copy)`
+						]
+					});
+				}
+				// Path was provided but doesn't exist on this beacon — log and fall
+				// through to the HTTP path so we still satisfy the request.
+				pTask.log.warn(`File Transfer: SourceLocalPath [${tmpSourceLocalPath}] does not exist on this beacon, falling back to HTTP transfer.`);
+				if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[FileTransfer] SourceLocalPath was set but file is missing on this beacon — the requesting beacon doesn't actually share this filesystem at the expected path.`);
+				}
+			}
+			else if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[FileTransfer] no SourceLocalPath in settings — running standard HTTP download path. (Either resolve-address chose 'direct'/'proxy', or the operation graph isn't wiring resolve.LocalPath → transfer.SourceLocalPath.)`);
+			}
 
 			if (!tmpSourceURL)
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0 },
+					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0, Strategy: '' },
 					Log: ['File Transfer: no SourceURL provided.']
 				});
 			}
@@ -197,7 +360,7 @@ module.exports =
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0 },
+					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0, Strategy: '' },
 					Log: ['File Transfer: no Filename provided.']
 				});
 			}
@@ -467,7 +630,7 @@ function _pipeToFile(pResponse, pOutputPath, pStartTime, pFilename, pTask, fCall
 
 		return fCallback(null, {
 			EventToFire: 'Complete',
-			Outputs: { LocalPath: pOutputPath, BytesTransferred: tmpBytes, DurationMs: tmpDuration },
+			Outputs: { LocalPath: pOutputPath, BytesTransferred: tmpBytes, DurationMs: tmpDuration, Strategy: 'http' },
 			Log: [
 				`Downloaded: ${pFilename}`,
 				`Size: ${tmpBytes} bytes`,

package/source/services/tasks/platform/definitions/file-transfer.json

@@ -2,7 +2,7 @@
 	"Hash": "file-transfer",
 	"Type": "file-transfer",
 	"Name": "File Transfer",
-	"Description": "Download a file from a URL to the operation's staging directory. Streams the download — no base64 encoding. Logs bytes transferred and duration for visibility in the manifest.",
+	"Description": "Download a file from a URL to the operation's staging directory. Streams the download — no base64 encoding. When SourceLocalPath is provided (set by resolve-address with a shared-fs strategy), the task short-circuits and returns that path directly without copying anything. Logs bytes transferred and duration for visibility in the manifest.",
 	"Category": "platform",
 	"Capability": "Data Transfer",
 	"Action": "Download",
@@ -13,14 +13,17 @@
 		{ "Name": "Error", "IsError": true }
 	],
 	"SettingsInputs": [
-		{ "Name": "SourceURL", "DataType": "String", "Required": true, "Description": "URL to download from" },
-		{ "Name": "Filename", "DataType": "String", "Required": true, "Description": "Filename to save as in the staging directory" },
-		{ "Name": "AffinityKey", "DataType": "String", "Required": false, "Description": "Affinity key for caching (same key skips re-download)" }
+		{ "Name": "SourceURL", "DataType": "String", "Required": false, "Description": "URL to download from. Required unless SourceLocalPath is provided." },
+		{ "Name": "SourceLocalPath", "DataType": "String", "Required": false, "Description": "Absolute filesystem path to read directly. When set and the file exists, the HTTP download is skipped entirely and BytesTransferred reports 0. Used by the shared-fs reachability strategy." },
+		{ "Name": "Filename", "DataType": "String", "Required": false, "Description": "Filename to save as in the staging directory. Required unless SourceLocalPath is provided." },
+		{ "Name": "AffinityKey", "DataType": "String", "Required": false, "Description": "Affinity key for caching (same key skips re-download)" },
+		{ "Name": "TimeoutMs", "DataType": "Number", "Required": false, "Description": "HTTP download timeout in milliseconds (default 300000)" }
 	],
 	"StateOutputs": [
-		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the downloaded file in staging" },
-		{ "Name": "BytesTransferred", "DataType": "Number", "Description": "Size of the downloaded file in bytes" },
-		{ "Name": "DurationMs", "DataType": "Number", "Description": "Download duration in milliseconds" }
+		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the file (downloaded to staging, or pointing at the shared-fs source when no copy was needed)" },
+		{ "Name": "BytesTransferred", "DataType": "Number", "Description": "Size of the downloaded file in bytes (0 when shared-fs zero-copy was used)" },
+		{ "Name": "DurationMs", "DataType": "Number", "Description": "Download duration in milliseconds" },
+		{ "Name": "Strategy", "DataType": "String", "Description": "Which path was taken: 'shared-fs' (zero-copy) or 'http' (downloaded)" }
 	],
-	"DefaultSettings": { "SourceURL": "", "Filename": "", "AffinityKey": "" }
+	"DefaultSettings": { "SourceURL": "", "SourceLocalPath": "", "Filename": "", "AffinityKey": "", "TimeoutMs": 300000 }
 }

package/source/services/tasks/platform/definitions/resolve-address.json

@@ -2,7 +2,7 @@
 	"Hash": "resolve-address",
 	"Type": "resolve-address",
 	"Name": "Resolve Address",
-	"Description": "Resolve a universal address (>beacon/context/path) to a concrete URL and metadata, with optional transfer strategy resolution (local/direct/proxy) when a requesting beacon is specified.",
+	"Description": "Resolve a universal address (>beacon/context/path) to a concrete URL and metadata, with optional transfer strategy resolution (local/shared-fs/direct/proxy) when a requesting beacon is specified.",
 	"Category": "platform",
 	"Capability": "Address Resolution",
 	"Action": "Resolve",
@@ -24,9 +24,10 @@
 		{ "Name": "Context", "DataType": "String", "Description": "Context name (e.g. File, Cache)" },
 		{ "Name": "Path", "DataType": "String", "Description": "Path within the context" },
 		{ "Name": "Filename", "DataType": "String", "Description": "Filename portion of the path" },
-		{ "Name": "Strategy", "DataType": "String", "Description": "Transfer strategy: local, direct, or proxy" },
+		{ "Name": "Strategy", "DataType": "String", "Description": "Transfer strategy: local, shared-fs, direct, or proxy" },
 		{ "Name": "DirectURL", "DataType": "String", "Description": "Direct beacon-to-beacon URL (when strategy is direct)" },
-		{ "Name": "ProxyURL", "DataType": "String", "Description": "Proxy URL through Ultravisor (when strategy is proxy)" }
+		{ "Name": "ProxyURL", "DataType": "String", "Description": "Proxy URL through Ultravisor (when strategy is proxy)" },
+		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the resource on the shared filesystem (when strategy is shared-fs); empty otherwise" }
 	],
 	"DefaultSettings": { "Address": "", "Destination": "", "RequestingBeaconID": "" }
 }